├── plugin
└── ziit.lua
├── lua
└── ziit
│ ├── status
│ └── init.lua
│ ├── config
│ └── init.lua
│ ├── http
│ └── init.lua
│ ├── queue
│ └── init.lua
│ ├── heartbeat
│ └── init.lua
│ ├── health.lua
│ └── init.lua
├── README.md
├── doc
└── ziit.txt
└── LICENSE
/plugin/ziit.lua:
--------------------------------------------------------------------------------
1 | if vim.g.loaded_ziit then
2 | return
3 | end
4 |
5 | if vim.fn.has('nvim-0.7') == 0 then
6 | vim.notify('Ziit: Requires Neovim 0.7+', vim.log.levels.ERROR)
7 | return
8 | end
9 |
10 | local has_plenary = pcall(require, 'plenary.curl')
11 | if not has_plenary then
12 | vim.notify('Ziit: Requires plenary.nvim', vim.log.levels.ERROR)
13 | return
14 | end
15 |
16 | vim.api.nvim_create_user_command('ZiitSetup', function(opts)
17 | local config = {}
18 |
19 | if opts.args and opts.args ~= '' then
20 | local parts = vim.split(opts.args, ' ')
21 | for _, part in ipairs(parts) do
22 | local key, value = part:match('([^=]+)=(.+)')
23 | if key and value then
24 | if key == 'enabled' or key == 'debug' then
25 | config[key] = value == 'true'
26 | elseif key == 'heartbeat_interval' or key == 'offline_sync_interval' or key == 'max_heartbeat_age' then
27 | config[key] = tonumber(value)
28 | else
29 | config[key] = value
30 | end
31 | end
32 | end
33 | end
34 |
35 | require('ziit').setup(config)
36 | end, {
37 | nargs = '*',
38 | desc = 'Setup Ziit plugin with optional configuration',
39 | complete = function()
40 | return {
41 | 'api_key=',
42 | 'base_url=https://ziit.app',
43 | 'enabled=true',
44 | 'debug=false',
45 | 'heartbeat_interval=120',
46 | 'offline_sync_interval=300',
47 | }
48 | end,
49 | })
50 |
51 | local function auto_setup()
52 | local config_file = vim.fn.expand('~/.ziit.json')
53 | if vim.fn.filereadable(config_file) == 1 then
54 | require('ziit').setup()
55 | return
56 | end
57 |
58 | local git_dir = vim.fn.finddir('.git', '.;')
59 | if git_dir ~= '' then
60 | local project_config = vim.fn.fnamemodify(git_dir, ':h') .. '/.ziit.json'
61 | if vim.fn.filereadable(project_config) == 1 then
62 | require('ziit').setup()
63 | return
64 | end
65 | end
66 |
67 | if vim.g.ziit_config then
68 | require('ziit').setup()
69 | end
70 | end
71 |
72 | vim.defer_fn(auto_setup, 100)
73 |
74 | vim.g.loaded_ziit = 1
75 |
--------------------------------------------------------------------------------
/lua/ziit/status/init.lua:
--------------------------------------------------------------------------------
1 | local M = {}
2 |
3 | local status_cache = {
4 | enabled = false,
5 | queue_size = 0,
6 | last_update = 0,
7 | }
8 |
9 | local function update_cache()
10 | local current_time = vim.loop.hrtime()
11 |
12 | if current_time - status_cache.last_update < 5e9 then
13 | return
14 | end
15 |
16 | local config = require('ziit.config')
17 | local queue = require('ziit.queue')
18 |
19 | status_cache.enabled = config.is_enabled()
20 | status_cache.queue_size = queue.size()
21 | status_cache.last_update = current_time
22 | end
23 |
24 | function M.get_status_text()
25 | update_cache()
26 |
27 | if not status_cache.enabled then
28 | return ''
29 | end
30 |
31 | local icon = '⏱'
32 | local text = 'Ziit'
33 |
34 | if status_cache.queue_size > 0 then
35 | text = text .. ' (' .. status_cache.queue_size .. ')'
36 | end
37 |
38 | return icon .. ' ' .. text
39 | end
40 |
41 | function M.get_status_highlight()
42 | update_cache()
43 |
44 | if not status_cache.enabled then
45 | return 'Comment'
46 | end
47 |
48 | if status_cache.queue_size > 0 then
49 | return 'WarningMsg'
50 | end
51 |
52 | return 'StatusLine'
53 | end
54 |
55 | function M.setup_lualine()
56 | if not pcall(require, 'lualine') then
57 | return false
58 | end
59 |
60 | local lualine = require('lualine')
61 | local config = lualine.get_config()
62 |
63 | local ziit_component = {
64 | function()
65 | return M.get_status_text()
66 | end,
67 | color = function()
68 | local hl = M.get_status_highlight()
69 | if hl == 'WarningMsg' then
70 | return { fg = '#ff9e00' }
71 | elseif hl == 'Comment' then
72 | return { fg = '#6c7086' }
73 | end
74 | return nil
75 | end,
76 | cond = function()
77 | return M.get_status_text() ~= ''
78 | end,
79 | }
80 |
81 | if not config.sections.lualine_x then
82 | config.sections.lualine_x = {}
83 | end
84 |
85 | table.insert(config.sections.lualine_x, ziit_component)
86 |
87 | lualine.setup(config)
88 | return true
89 | end
90 |
91 | function M.setup_statusline()
92 | if M.setup_lualine() then
93 | return
94 | end
95 |
96 | local old_statusline = vim.o.statusline
97 |
98 | local function get_ziit_status()
99 | local status = M.get_status_text()
100 | if status == '' then
101 | return ''
102 | end
103 | return '%#' .. M.get_status_highlight() .. '#' .. status .. '%*'
104 | end
105 |
106 | if old_statusline and old_statusline ~= '' then
107 | vim.o.statusline = old_statusline .. ' ' .. '%{v:lua.require("ziit.status").get_statusline_component()}'
108 | else
109 | vim.o.statusline = '%f %m%r%h%w%=%{v:lua.require("ziit.status").get_statusline_component()} %l,%c %P'
110 | end
111 | end
112 |
113 | function M.get_statusline_component()
114 | local status = M.get_status_text()
115 | if status == '' then
116 | return ''
117 | end
118 | return status
119 | end
120 |
121 | function M.refresh()
122 | status_cache.last_update = 0
123 | update_cache()
124 | end
125 |
126 | return M
127 |
--------------------------------------------------------------------------------
/lua/ziit/config/init.lua:
--------------------------------------------------------------------------------
1 | local Path = require('plenary.path')
2 |
3 | local M = {}
4 |
5 | M.defaults = {
6 | base_url = 'https://ziit.app',
7 | api_key = nil,
8 | enabled = true,
9 | debug = false,
10 | heartbeat_interval = 120,
11 | offline_sync_interval = 300,
12 | max_heartbeat_age = 86400,
13 | use_absolute_paths = true,
14 | exclude_patterns = {
15 | '%.git/',
16 | '%.svn/',
17 | '%.hg/',
18 | '/tmp/',
19 | '%.tmp$',
20 | '%.log$',
21 | 'node_modules/',
22 | '%.cache/',
23 | },
24 | }
25 |
26 | local config = vim.tbl_deep_extend('force', {}, M.defaults)
27 |
28 | local function merge_config(user_config)
29 | config = vim.tbl_deep_extend('force', config, user_config or {})
30 | end
31 |
32 | local function load_config_file(filepath)
33 | local path = Path:new(filepath)
34 | if not path:exists() then
35 | return nil
36 | end
37 |
38 | local content = path:read()
39 | if not content then
40 | return nil
41 | end
42 |
43 | local ok, decoded = pcall(vim.json.decode, content)
44 | if not ok then
45 | vim.notify('Ziit: Failed to parse config file: ' .. filepath, vim.log.levels.WARN)
46 | return nil
47 | end
48 |
49 | return decoded
50 | end
51 |
52 | local function find_project_config()
53 | local current_dir = vim.fn.getcwd()
54 | local path = Path:new(current_dir)
55 |
56 | while path and tostring(path) ~= '/' do
57 | local config_file = path / '.ziit.json'
58 | if config_file:exists() then
59 | return tostring(config_file)
60 | end
61 | path = path:parent()
62 | end
63 |
64 | return nil
65 | end
66 |
67 | local function load_env_config()
68 | local env_config = {}
69 |
70 | local api_key = vim.fn.getenv('ZIIT_API_KEY')
71 | if api_key and api_key ~= vim.v.null and api_key ~= '' then
72 | env_config.api_key = api_key
73 | end
74 |
75 | local base_url = vim.fn.getenv('ZIIT_BASE_URL')
76 | if base_url and base_url ~= vim.v.null and base_url ~= '' then
77 | env_config.base_url = base_url
78 | end
79 |
80 | local enabled = vim.fn.getenv('ZIIT_ENABLED')
81 | if enabled and enabled ~= vim.v.null and enabled ~= '' then
82 | env_config.enabled = enabled:lower() == 'true' or enabled == '1'
83 | end
84 |
85 | local debug = vim.fn.getenv('ZIIT_DEBUG')
86 | if debug and debug ~= vim.v.null and debug ~= '' then
87 | env_config.debug = debug:lower() == 'true' or debug == '1'
88 | end
89 |
90 | return next(env_config) and env_config or nil
91 | end
92 |
93 | function M.load()
94 | local configs = {}
95 |
96 | local env_config = load_env_config()
97 | if env_config then
98 | table.insert(configs, env_config)
99 | end
100 |
101 | local home_config = load_config_file(vim.fn.expand('~/.ziit.json'))
102 | if home_config then
103 | table.insert(configs, home_config)
104 | end
105 |
106 | local project_config_path = find_project_config()
107 | if project_config_path then
108 | local project_config = load_config_file(project_config_path)
109 | if project_config then
110 | table.insert(configs, project_config)
111 | end
112 | end
113 |
114 | if vim.g.ziit_config then
115 | table.insert(configs, vim.g.ziit_config)
116 | end
117 |
118 | for _, user_config in ipairs(configs) do
119 | merge_config(user_config)
120 | end
121 |
122 | if M.is_debug() then
123 | vim.notify('Ziit: Configuration loaded', vim.log.levels.INFO)
124 | end
125 | end
126 |
127 | function M.get(key)
128 | if key then
129 | return config[key]
130 | end
131 | return config
132 | end
133 |
134 | function M.set(key, value)
135 | config[key] = value
136 | end
137 |
138 | function M.is_enabled()
139 | return config.enabled and config.api_key ~= nil
140 | end
141 |
142 | function M.is_debug()
143 | return config.debug
144 | end
145 |
146 | function M.should_exclude(filepath)
147 | if not filepath then
148 | return true
149 | end
150 |
151 | for _, pattern in ipairs(config.exclude_patterns) do
152 | if string.match(filepath, pattern) then
153 | return true
154 | end
155 | end
156 |
157 | return false
158 | end
159 |
160 | function M.validate()
161 | local errors = {}
162 |
163 | if not config.api_key then
164 | table.insert(errors, 'API key is required')
165 | end
166 |
167 | if not config.base_url then
168 | table.insert(errors, 'Base URL is required')
169 | end
170 |
171 | if #errors > 0 then
172 | return false, errors
173 | end
174 |
175 | return true, {}
176 | end
177 |
178 | function M.setup(user_config)
179 | merge_config(user_config)
180 | M.load()
181 |
182 | local valid, errors = M.validate()
183 | if not valid and M.is_debug() then
184 | vim.notify('Ziit: Configuration errors: ' .. table.concat(errors, ', '), vim.log.levels.ERROR)
185 | end
186 | end
187 |
188 | return M
189 |
--------------------------------------------------------------------------------
/lua/ziit/http/init.lua:
--------------------------------------------------------------------------------
1 | local curl = require('plenary.curl')
2 |
3 | local M = {}
4 |
5 | local function build_url(endpoint)
6 | local config = require('ziit.config')
7 | local base_url = config.get('base_url')
8 |
9 | if not base_url then
10 | return nil
11 | end
12 |
13 | base_url = base_url:gsub('/$', '')
14 | endpoint = endpoint:gsub('^/', '')
15 |
16 | return base_url .. '/api/external/' .. endpoint
17 | end
18 |
19 | local function get_headers()
20 | local config = require('ziit.config')
21 | local api_key = config.get('api_key')
22 |
23 | if not api_key then
24 | return nil
25 | end
26 |
27 | return {
28 | ['Content-Type'] = 'application/json',
29 | ['Authorization'] = 'Bearer ' .. api_key,
30 | ['User-Agent'] = 'ziit-neovim/1.0.0',
31 | }
32 | end
33 |
34 | local function handle_response(response, success_callback, error_callback)
35 | local config = require('ziit.config')
36 |
37 | if config.is_debug() then
38 | vim.notify(string.format('Ziit HTTP: %d %s', response.status, response.body or ''), vim.log.levels.DEBUG)
39 | end
40 |
41 | if response.status >= 200 and response.status < 300 then
42 | if success_callback then
43 | success_callback(response)
44 | end
45 | else
46 | local error_msg = string.format('HTTP %d: %s', response.status, response.body or 'Unknown error')
47 |
48 | if config.is_debug() then
49 | vim.notify('Ziit: ' .. error_msg, vim.log.levels.ERROR)
50 | end
51 |
52 | if error_callback then
53 | error_callback(error_msg, response)
54 | end
55 | end
56 | end
57 |
58 | function M.send_heartbeat(heartbeat, callback)
59 | local url = build_url('heartbeats')
60 | local headers = get_headers()
61 |
62 | if not url or not headers then
63 | if callback then
64 | callback(false, 'Configuration error: missing URL or API key')
65 | end
66 | return
67 | end
68 |
69 | local body = vim.json.encode(heartbeat)
70 |
71 | curl.post(url, {
72 | body = body,
73 | headers = headers,
74 | timeout = 10000,
75 | callback = function(response)
76 | handle_response(response, function(res)
77 | if callback then
78 | callback(true, res)
79 | end
80 | end, function(error_msg, res)
81 | if callback then
82 | callback(false, error_msg)
83 | end
84 | end)
85 | end,
86 | })
87 | end
88 |
89 | function M.send_batch(heartbeats, callback)
90 | if not heartbeats or #heartbeats == 0 then
91 | if callback then
92 | callback(true, 'No heartbeats to send')
93 | end
94 | return
95 | end
96 |
97 | if #heartbeats > 1000 then
98 | heartbeats = vim.list_slice(heartbeats, 1, 1000)
99 | end
100 |
101 | local url = build_url('batch')
102 | local headers = get_headers()
103 |
104 | if not url or not headers then
105 | if callback then
106 | callback(false, 'Configuration error: missing URL or API key')
107 | end
108 | return
109 | end
110 |
111 | local body = vim.json.encode(heartbeats)
112 |
113 | curl.post(url, {
114 | body = body,
115 | headers = headers,
116 | timeout = 30000,
117 | callback = function(response)
118 | handle_response(response, function(res)
119 | if callback then
120 | callback(true, res)
121 | end
122 | end, function(error_msg, res)
123 | if callback then
124 | callback(false, error_msg)
125 | end
126 | end)
127 | end,
128 | })
129 | end
130 |
131 | function M.get_stats(callback)
132 | local url = build_url('stats')
133 | local headers = get_headers()
134 |
135 | if not url or not headers then
136 | if callback then
137 | callback(false, 'Configuration error: missing URL or API key')
138 | end
139 | return
140 | end
141 |
142 | local timezone_offset = os.difftime(os.time(), os.time(os.date('!*t')))
143 |
144 | curl.get(url, {
145 | query = {
146 | timeRange = 'today',
147 | midnightOffsetSeconds = tostring(timezone_offset),
148 | },
149 | headers = headers,
150 | timeout = 10000,
151 | callback = function(response)
152 | handle_response(response, function(res)
153 | local ok, data = pcall(vim.json.decode, res.body)
154 | if ok then
155 | if callback then
156 | callback(true, data)
157 | end
158 | else
159 | if callback then
160 | callback(false, 'Failed to parse response')
161 | end
162 | end
163 | end, function(error_msg)
164 | if callback then
165 | callback(false, error_msg)
166 | end
167 | end)
168 | end,
169 | })
170 | end
171 |
172 | function M.test_connection(callback)
173 | local config = require('ziit.config')
174 |
175 | if not config.is_enabled() then
176 | if callback then
177 | callback(false, 'Plugin not enabled or API key missing')
178 | end
179 | return
180 | end
181 |
182 | M.get_stats(function(success, result)
183 | if callback then
184 | if success then
185 | callback(true, 'Connection successful')
186 | else
187 | callback(false, 'Connection failed: ' .. (result or 'Unknown error'))
188 | end
189 | end
190 | end)
191 | end
192 |
193 | return M
194 |
--------------------------------------------------------------------------------
/lua/ziit/queue/init.lua:
--------------------------------------------------------------------------------
1 | local Path = require('plenary.path')
2 |
3 | local M = {}
4 |
5 | local queue_file = nil
6 | local queue_cache = {}
7 | local is_dirty = false
8 |
9 | local function get_queue_file_path()
10 | if queue_file then
11 | return queue_file
12 | end
13 |
14 | local data_dir = vim.fn.stdpath('data')
15 | local ziit_dir = Path:new(data_dir, 'ziit')
16 |
17 | if not ziit_dir:exists() then
18 | ziit_dir:mkdir({ parents = true })
19 | end
20 |
21 | queue_file = ziit_dir / 'queue.json'
22 | return queue_file
23 | end
24 |
25 | local function load_queue()
26 | local file_path = get_queue_file_path()
27 |
28 | if not file_path:exists() then
29 | queue_cache = {}
30 | return
31 | end
32 |
33 | local content = file_path:read()
34 | if not content or content == '' then
35 | queue_cache = {}
36 | return
37 | end
38 |
39 | local ok, data = pcall(vim.json.decode, content)
40 | if ok and type(data) == 'table' then
41 | queue_cache = data
42 | else
43 | queue_cache = {}
44 | local config = require('ziit.config')
45 | if config.is_debug() then
46 | vim.notify('Ziit: Failed to load queue file, starting with empty queue', vim.log.levels.WARN)
47 | end
48 | end
49 | end
50 |
51 | local function save_queue()
52 | if not is_dirty then
53 | return
54 | end
55 |
56 | local file_path = get_queue_file_path()
57 | local content = vim.json.encode(queue_cache)
58 |
59 | file_path:write(content, 'w')
60 | is_dirty = false
61 | end
62 |
63 | local function clean_old_heartbeats()
64 | local config = require('ziit.config')
65 | local max_age = config.get('max_heartbeat_age')
66 | local cutoff_time = os.time() - max_age
67 |
68 | local cleaned = {}
69 | for _, heartbeat in ipairs(queue_cache) do
70 | local timestamp_str = heartbeat.timestamp
71 | if timestamp_str then
72 | local timestamp = os.time({
73 | year = tonumber(timestamp_str:sub(1, 4)),
74 | month = tonumber(timestamp_str:sub(6, 7)),
75 | day = tonumber(timestamp_str:sub(9, 10)),
76 | hour = tonumber(timestamp_str:sub(12, 13)),
77 | min = tonumber(timestamp_str:sub(15, 16)),
78 | sec = tonumber(timestamp_str:sub(18, 19)),
79 | })
80 |
81 | if timestamp > cutoff_time then
82 | table.insert(cleaned, heartbeat)
83 | end
84 | end
85 | end
86 |
87 | if #cleaned ~= #queue_cache then
88 | queue_cache = cleaned
89 | is_dirty = true
90 |
91 | local config = require('ziit.config')
92 | if config.is_debug() then
93 | vim.notify(string.format('Ziit: Cleaned %d old heartbeats', #queue_cache - #cleaned), vim.log.levels.INFO)
94 | end
95 | end
96 | end
97 |
98 | function M.init()
99 | load_queue()
100 | clean_old_heartbeats()
101 | end
102 |
103 | function M.add(heartbeat)
104 | if not heartbeat then
105 | return
106 | end
107 |
108 | table.insert(queue_cache, heartbeat)
109 | is_dirty = true
110 |
111 | clean_old_heartbeats()
112 | save_queue()
113 |
114 | local config = require('ziit.config')
115 | if config.is_debug() then
116 | vim.notify(string.format('Ziit: Added heartbeat to queue (total: %d)', #queue_cache), vim.log.levels.DEBUG)
117 | end
118 | end
119 |
120 | function M.get_all()
121 | return vim.deepcopy(queue_cache)
122 | end
123 |
124 | function M.remove_batch(count)
125 | if count <= 0 or #queue_cache == 0 then
126 | return
127 | end
128 |
129 | count = math.min(count, #queue_cache)
130 |
131 | for i = 1, count do
132 | table.remove(queue_cache, 1)
133 | end
134 |
135 | is_dirty = true
136 | save_queue()
137 |
138 | local config = require('ziit.config')
139 | if config.is_debug() then
140 | vim.notify(
141 | string.format('Ziit: Removed %d heartbeats from queue (remaining: %d)', count, #queue_cache),
142 | vim.log.levels.DEBUG
143 | )
144 | end
145 | end
146 |
147 | function M.clear()
148 | queue_cache = {}
149 | is_dirty = true
150 | save_queue()
151 |
152 | local config = require('ziit.config')
153 | if config.is_debug() then
154 | vim.notify('Ziit: Cleared queue', vim.log.levels.INFO)
155 | end
156 | end
157 |
158 | function M.size()
159 | return #queue_cache
160 | end
161 |
162 | function M.is_empty()
163 | return #queue_cache == 0
164 | end
165 |
166 | function M.sync()
167 | if M.is_empty() then
168 | return
169 | end
170 |
171 | local http = require('ziit.http')
172 | local heartbeats = M.get_all()
173 | local batch_size = math.min(#heartbeats, 1000)
174 | local batch = vim.list_slice(heartbeats, 1, batch_size)
175 |
176 | http.send_batch(batch, function(success, result)
177 | if success then
178 | M.remove_batch(batch_size)
179 |
180 | local config = require('ziit.config')
181 | if config.is_debug() then
182 | vim.notify(string.format('Ziit: Successfully synced %d heartbeats', batch_size), vim.log.levels.INFO)
183 | end
184 |
185 | if not M.is_empty() then
186 | vim.defer_fn(function()
187 | M.sync()
188 | end, 1000)
189 | end
190 | else
191 | local config = require('ziit.config')
192 | if config.is_debug() then
193 | vim.notify('Ziit: Failed to sync heartbeats: ' .. (result or 'Unknown error'), vim.log.levels.ERROR)
194 | end
195 | end
196 | end)
197 | end
198 |
199 | function M.start_sync_timer()
200 | local config = require('ziit.config')
201 | local interval = config.get('offline_sync_interval')
202 |
203 | if not interval or interval <= 0 then
204 | return
205 | end
206 |
207 | local timer = vim.loop.new_timer()
208 | if timer then
209 | timer:start(
210 | interval * 1000,
211 | interval * 1000,
212 | vim.schedule_wrap(function()
213 | if not M.is_empty() then
214 | M.sync()
215 | end
216 | end)
217 | )
218 | end
219 | end
220 |
221 | return M
222 |
--------------------------------------------------------------------------------
/lua/ziit/heartbeat/init.lua:
--------------------------------------------------------------------------------
1 | local Path = require('plenary.path')
2 |
3 | local M = {}
4 |
5 | local function get_git_branch()
6 | local git_dir = vim.fn.finddir('.git', '.;')
7 | if git_dir == '' then
8 | return nil
9 | end
10 |
11 | local head_file = Path:new(git_dir, 'HEAD')
12 | if not head_file:exists() then
13 | return nil
14 | end
15 |
16 | local content = head_file:read()
17 | if not content then
18 | return nil
19 | end
20 |
21 | local branch = content:match('ref: refs/heads/(.+)')
22 | if branch then
23 | return vim.trim(branch)
24 | end
25 |
26 | return nil
27 | end
28 |
29 | local function get_git_project()
30 | local git_dir = vim.fn.finddir('.git', '.;')
31 | if git_dir == '' then
32 | return nil
33 | end
34 |
35 | local git_parent = Path:new(git_dir):parent()
36 | return git_parent:absolute():match('([^/]+)$')
37 | end
38 |
39 | local function get_language_from_filename(filename)
40 | if not filename then
41 | return nil
42 | end
43 |
44 | local ext = filename:match('%.([^%.]+)$')
45 | if not ext then
46 | return nil
47 | end
48 |
49 | local language_map = {
50 | lua = 'Lua',
51 | js = 'JavaScript',
52 | ts = 'TypeScript',
53 | jsx = 'JavaScript',
54 | tsx = 'TypeScript',
55 | py = 'Python',
56 | rb = 'Ruby',
57 | go = 'Go',
58 | rs = 'Rust',
59 | c = 'C',
60 | cpp = 'C++',
61 | cc = 'C++',
62 | cxx = 'C++',
63 | h = 'C',
64 | hpp = 'C++',
65 | java = 'Java',
66 | php = 'PHP',
67 | cs = 'C#',
68 | sh = 'Shell',
69 | bash = 'Shell',
70 | zsh = 'Shell',
71 | fish = 'Shell',
72 | vim = 'Vim Script',
73 | html = 'HTML',
74 | css = 'CSS',
75 | scss = 'SCSS',
76 | sass = 'Sass',
77 | json = 'JSON',
78 | xml = 'XML',
79 | yaml = 'YAML',
80 | yml = 'YAML',
81 | toml = 'TOML',
82 | md = 'Markdown',
83 | txt = 'Text',
84 | sql = 'SQL',
85 | r = 'R',
86 | swift = 'Swift',
87 | kt = 'Kotlin',
88 | dart = 'Dart',
89 | elm = 'Elm',
90 | hs = 'Haskell',
91 | clj = 'Clojure',
92 | ex = 'Elixir',
93 | exs = 'Elixir',
94 | erl = 'Erlang',
95 | pl = 'Perl',
96 | scala = 'Scala',
97 | groovy = 'Groovy',
98 | dockerfile = 'Dockerfile',
99 | }
100 |
101 | return language_map[ext:lower()]
102 | end
103 |
104 | local function get_language_from_filetype()
105 | local ft = vim.bo.filetype
106 | if not ft or ft == '' then
107 | return nil
108 | end
109 |
110 | local filetype_map = {
111 | lua = 'Lua',
112 | javascript = 'JavaScript',
113 | typescript = 'TypeScript',
114 | python = 'Python',
115 | ruby = 'Ruby',
116 | go = 'Go',
117 | rust = 'Rust',
118 | c = 'C',
119 | cpp = 'C++',
120 | java = 'Java',
121 | php = 'PHP',
122 | cs = 'C#',
123 | sh = 'Shell',
124 | vim = 'Vim Script',
125 | html = 'HTML',
126 | css = 'CSS',
127 | scss = 'SCSS',
128 | sass = 'Sass',
129 | json = 'JSON',
130 | xml = 'XML',
131 | yaml = 'YAML',
132 | toml = 'TOML',
133 | markdown = 'Markdown',
134 | text = 'Text',
135 | sql = 'SQL',
136 | r = 'R',
137 | swift = 'Swift',
138 | kotlin = 'Kotlin',
139 | dart = 'Dart',
140 | elm = 'Elm',
141 | haskell = 'Haskell',
142 | clojure = 'Clojure',
143 | elixir = 'Elixir',
144 | erlang = 'Erlang',
145 | perl = 'Perl',
146 | scala = 'Scala',
147 | groovy = 'Groovy',
148 | dockerfile = 'Dockerfile',
149 | }
150 |
151 | return filetype_map[ft]
152 | end
153 |
154 | local function get_os()
155 | local uname = vim.loop.os_uname()
156 | if uname then
157 | return uname.sysname
158 | end
159 |
160 | if vim.fn.has('win32') == 1 then
161 | return 'Windows'
162 | elseif vim.fn.has('mac') == 1 then
163 | return 'Darwin'
164 | elseif vim.fn.has('unix') == 1 then
165 | return 'Linux'
166 | end
167 |
168 | return 'Unknown'
169 | end
170 |
171 | local function get_current_file()
172 | local bufnr = vim.api.nvim_get_current_buf()
173 | local filepath = vim.api.nvim_buf_get_name(bufnr)
174 |
175 | if filepath == '' then
176 | return nil
177 | end
178 |
179 | if
180 | vim.startswith(filepath, 'fugitive://')
181 | or vim.startswith(filepath, 'oil://')
182 | or vim.startswith(filepath, 'neo-tree://')
183 | or vim.startswith(filepath, 'NvimTree_')
184 | then
185 | return nil
186 | end
187 |
188 | local path = Path:new(filepath)
189 | if not path:exists() then
190 | return nil
191 | end
192 |
193 | return filepath
194 | end
195 |
196 | local function format_timestamp()
197 | return os.date('!%Y-%m-%dT%H:%M:%SZ')
198 | end
199 |
200 | function M.create()
201 | local current_file = get_current_file()
202 |
203 | if not current_file then
204 | return nil
205 | end
206 |
207 | local config = require('ziit.config')
208 | if config.should_exclude(current_file) then
209 | return nil
210 | end
211 |
212 | local language = get_language_from_filetype() or get_language_from_filename(current_file)
213 | local branch = get_git_branch()
214 | local project = get_git_project()
215 |
216 | local config = require('ziit.config')
217 | local file_path = current_file
218 |
219 | -- Convert to relative path if configured
220 | if not config.get('use_absolute_paths') then
221 | local cwd = vim.fn.getcwd()
222 | if vim.startswith(current_file, cwd) then
223 | file_path = vim.fn.fnamemodify(current_file, ':.')
224 | end
225 | end
226 |
227 | local heartbeat = {
228 | timestamp = format_timestamp(),
229 | editor = 'Neovim',
230 | os = get_os(),
231 | file = file_path,
232 | }
233 |
234 | if language then
235 | heartbeat.language = language
236 | end
237 |
238 | if branch then
239 | heartbeat.branch = branch
240 | end
241 |
242 | if project then
243 | heartbeat.project = project
244 | end
245 |
246 | return heartbeat
247 | end
248 |
249 | return M
250 |
--------------------------------------------------------------------------------
/lua/ziit/health.lua:
--------------------------------------------------------------------------------
1 | local M = {}
2 |
3 | local function check_plenary()
4 | local ok, _ = pcall(require, 'plenary.curl')
5 | if ok then
6 | vim.health.ok('plenary.nvim is available')
7 | return true
8 | else
9 | vim.health.error('plenary.nvim is not installed', {
10 | 'Install plenary.nvim: https://github.com/nvim-lua/plenary.nvim',
11 | 'Required for HTTP requests and file operations',
12 | })
13 | return false
14 | end
15 | end
16 |
17 | local function check_neovim_version()
18 | if vim.fn.has('nvim-0.7') == 1 then
19 | vim.health.ok('Neovim version is supported (' .. vim.inspect(vim.version()) .. ')')
20 | return true
21 | else
22 | vim.health.error('Neovim version is too old', {
23 | 'Requires Neovim 0.7 or later',
24 | 'Current version: ' .. vim.inspect(vim.version()),
25 | })
26 | return false
27 | end
28 | end
29 |
30 | local function check_configuration()
31 | local config = require('ziit.config')
32 | local conf = config.get()
33 |
34 | if not conf.api_key then
35 | vim.health.error('No API key configured', {
36 | "Set API key via setup(): require('ziit').setup({api_key = 'your-key'})",
37 | "Or via environment: export ZIIT_API_KEY='your-key'",
38 | 'Or via config file: ~/.ziit.json with {"api_key": "your-key"}',
39 | })
40 | return false
41 | end
42 |
43 | if conf.api_key == 'test-api-key' or conf.api_key == 'your-api-key-here' then
44 | vim.health.warn('Using test/placeholder API key', {
45 | 'Replace with your actual Ziit API key',
46 | })
47 | else
48 | vim.health.ok('API key is configured')
49 | end
50 |
51 | if conf.base_url then
52 | vim.health.ok('Base URL: ' .. conf.base_url)
53 | else
54 | vim.health.error('No base URL configured')
55 | return false
56 | end
57 |
58 | return true
59 | end
60 |
61 | local function check_plugin_status()
62 | local config = require('ziit.config')
63 |
64 | if config.is_enabled() then
65 | vim.health.ok('Plugin is enabled and ready')
66 |
67 | local queue = require('ziit.queue')
68 | local queue_size = queue.size()
69 |
70 | if queue_size == 0 then
71 | vim.health.ok('No queued heartbeats (online)')
72 | else
73 | vim.health.warn('Heartbeats queued: ' .. queue_size, {
74 | 'This indicates offline mode or connection issues',
75 | 'Run :ZiitSync to manually sync queued heartbeats',
76 | 'Check your network connection and server URL',
77 | })
78 | end
79 | else
80 | vim.health.error('Plugin is disabled', {
81 | "Enable with: require('ziit.config').set('enabled', true)",
82 | 'Or ensure API key is configured',
83 | })
84 | return false
85 | end
86 |
87 | return true
88 | end
89 |
90 | local function check_file_permissions()
91 | local data_dir = vim.fn.stdpath('data')
92 |
93 | if vim.fn.isdirectory(data_dir) == 0 then
94 | vim.health.error('Neovim data directory not accessible: ' .. data_dir)
95 | return false
96 | end
97 |
98 | if vim.fn.filewritable(data_dir) == 0 then
99 | vim.health.error('Cannot write to data directory: ' .. data_dir, {
100 | 'Check directory permissions',
101 | 'Required for offline queue storage',
102 | })
103 | return false
104 | end
105 |
106 | vim.health.ok('File system permissions are correct')
107 | return true
108 | end
109 |
110 | local function check_connection_readiness()
111 | local config = require('ziit.config')
112 |
113 | if not config.is_enabled() then
114 | vim.health.info('Skipping connection check (plugin disabled)')
115 | return
116 | end
117 |
118 | local conf = config.get()
119 |
120 | -- Validate URL format
121 | if conf.base_url then
122 | if conf.base_url:match('^https?://') then
123 | vim.health.ok('Server URL format is valid')
124 | else
125 | vim.health.warn('Server URL should start with http:// or https://', {
126 | 'Current URL: ' .. conf.base_url,
127 | 'Example: https://ziit.app',
128 | })
129 | end
130 | end
131 |
132 | -- Check if API key looks reasonable
133 | if conf.api_key then
134 | if #conf.api_key >= 10 then
135 | vim.health.ok('API key length looks reasonable')
136 | else
137 | vim.health.warn('API key seems too short', {
138 | 'Current length: ' .. #conf.api_key .. ' characters',
139 | 'Make sure you have a valid Ziit API key',
140 | })
141 | end
142 | end
143 |
144 | vim.health.info('Use :ZiitTest to perform a live connection test')
145 | end
146 |
147 | local function show_debug_info()
148 | local config = require('ziit.config')
149 | local conf = config.get()
150 |
151 | vim.health.info('Configuration sources (in priority order):')
152 | vim.health.info('1. Lua setup() function')
153 | vim.health.info('2. Global variable vim.g.ziit_config')
154 | vim.health.info('3. Project .ziit.json file')
155 | vim.health.info('4. Home ~/.ziit.json file')
156 | vim.health.info('5. Environment variables')
157 |
158 | vim.health.info('Current settings:')
159 | vim.health.info('- Enabled: ' .. tostring(conf.enabled))
160 | vim.health.info('- Debug: ' .. tostring(conf.debug))
161 | vim.health.info('- Heartbeat interval: ' .. conf.heartbeat_interval .. 's')
162 | vim.health.info('- Offline sync interval: ' .. conf.offline_sync_interval .. 's')
163 | vim.health.info('- Max heartbeat age: ' .. conf.max_heartbeat_age .. 's')
164 |
165 | local queue = require('ziit.queue')
166 | vim.health.info('- Queue size: ' .. queue.size())
167 |
168 | local ziit = require('ziit')
169 | local status = ziit.get_status()
170 | if status.last_heartbeat then
171 | vim.health.info('- Last heartbeat: ' .. (status.last_heartbeat.timestamp or 'unknown'))
172 | else
173 | vim.health.info('- Last heartbeat: none')
174 | end
175 | end
176 |
177 | function M.check()
178 | vim.health.start('Ziit Time Tracking')
179 |
180 | local deps_ok = check_neovim_version() and check_plenary()
181 | if not deps_ok then
182 | vim.health.info('Fix dependency issues above before continuing')
183 | return
184 | end
185 |
186 | local perms_ok = check_file_permissions()
187 | local config_ok = check_configuration()
188 | local status_ok = check_plugin_status()
189 |
190 | if config_ok then
191 | check_connection_readiness()
192 | end
193 |
194 | vim.health.start('Ziit Debug Information')
195 | show_debug_info()
196 |
197 | if deps_ok and perms_ok and config_ok and status_ok then
198 | vim.health.start('Summary')
199 | vim.health.ok('Ziit plugin is healthy and ready to track activity!')
200 | end
201 | end
202 |
203 | return M
204 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # ziit-neovim
2 |
3 | A Neovim plugin for automatic time tracking with [Ziit](https://ziit.app). Track your coding activity seamlessly while you work.
4 |
5 | ## Features
6 |
7 | - 🕐 Automatic activity tracking with heartbeats
8 | - 📱 Offline queue management for unreliable connections
9 | - 📊 Status bar integration (lualine support included)
10 | - ⚙️ Configurable tracking intervals and exclusions
11 | - 🎯 Smart project and language detection
12 | - 🌿 Git branch tracking
13 | - 🔧 Comprehensive command interface
14 | - 🐛 Debug mode for troubleshooting
15 |
16 | ## Requirements
17 |
18 | - [plenary.nvim](https://github.com/nvim-lua/plenary.nvim)
19 | - A Ziit server instance and API key
20 |
21 | ## Installation
22 |
23 | ### Using [lazy.nvim](https://github.com/folke/lazy.nvim)
24 |
25 | ```lua
26 | {
27 | 'your-username/ziit-neovim',
28 | dependencies = { 'nvim-lua/plenary.nvim' },
29 | config = function()
30 | require('ziit').setup({
31 | api_key = 'your-api-key-here',
32 | -- base_url = 'https://your-ziit-instance.com' -- optional, defaults to https://ziit.app
33 | })
34 | end
35 | }
36 | ```
37 |
38 | ### Using [packer.nvim](https://github.com/wbthomason/packer.nvim)
39 |
40 | ```lua
41 | use {
42 | 'your-username/ziit-neovim',
43 | requires = { 'nvim-lua/plenary.nvim' },
44 | config = function()
45 | require('ziit').setup({
46 | api_key = 'your-api-key-here'
47 | })
48 | end
49 | }
50 | ```
51 |
52 | ## Configuration
53 |
54 | ### Lua Configuration
55 |
56 | ```lua
57 | require('ziit').setup({
58 | base_url = 'https://ziit.app', -- Ziit server URL
59 | api_key = 'your-api-key-here', -- Your Ziit API key (required)
60 | enabled = true, -- Enable/disable tracking
61 | debug = false, -- Enable debug logging
62 | heartbeat_interval = 120, -- Minimum seconds between heartbeats
63 | offline_sync_interval = 300, -- Seconds between offline sync attempts
64 | max_heartbeat_age = 86400, -- Maximum age of queued heartbeats (seconds)
65 | use_absolute_paths = true, -- Use absolute file paths (false for relative)
66 | exclude_patterns = { -- Patterns to exclude from tracking
67 | '%.git/',
68 | '%.svn/',
69 | 'node_modules/',
70 | '%.tmp$',
71 | '%.log$',
72 | }
73 | })
74 | ```
75 |
76 | ### Environment Variables
77 |
78 | The plugin supports environment variables (highest priority):
79 |
80 | ```bash
81 | export ZIIT_API_KEY="your-api-key-here"
82 | export ZIIT_BASE_URL="https://ziit.app"
83 | export ZIIT_ENABLED="true"
84 | export ZIIT_DEBUG="false"
85 | ```
86 |
87 | ### JSON Configuration Files
88 |
89 | The plugin supports configuration files in order of priority:
90 |
91 | 1. Environment variables (highest priority)
92 | 2. Project-specific: `.ziit.json` (in git root or current directory)
93 | 3. User-specific: `~/.ziit.json`
94 |
95 | Example `~/.ziit.json`:
96 |
97 | ```json
98 | {
99 | "api_key": "your-api-key-here",
100 | "base_url": "https://ziit.app",
101 | "enabled": true,
102 | "debug": false
103 | }
104 | ```
105 |
106 | ### Global Variable Configuration
107 |
108 | ```lua
109 | vim.g.ziit_config = {
110 | api_key = 'your-api-key-here',
111 | enabled = true
112 | }
113 | ```
114 |
115 | ## Usage
116 |
117 | The plugin automatically starts tracking once configured. It sends heartbeats based on your activity in Neovim.
118 |
119 | ### Commands
120 |
121 | | Command | Description |
122 | | ---------------------- | ------------------------------------------ |
123 | | `:ZiitSetup [options]` | Initialize plugin with optional parameters |
124 | | `:ZiitEnable` | Enable tracking |
125 | | `:ZiitDisable` | Disable tracking |
126 | | `:checkhealth ziit` | Check plugin health and status |
127 | | `:ZiitSync` | Manually sync queued heartbeats |
128 | | `:ZiitTest` | Test connection to Ziit server |
129 | | `:ZiitStats` | Show today's coding statistics |
130 | | `:ZiitClearQueue` | Clear the offline heartbeat queue |
131 | | `:ZiitDebugOn` | Enable debug mode |
132 | | `:ZiitDebugOff` | Disable debug mode |
133 | | `:ZiitDebugToggle` | Toggle debug mode |
134 |
135 | ### Status Bar Integration
136 |
137 | For **lualine** users, the plugin automatically integrates with your statusline showing:
138 |
139 | - ⏱ Ziit - Normal operation
140 | - ⏱ Ziit (5) - Offline with 5 queued heartbeats
141 |
142 | For custom statuslines:
143 |
144 | ```lua
145 | -- Get status text
146 | local status = require('ziit.status').get_status_text()
147 |
148 | -- Get highlight group
149 | local hl = require('ziit.status').get_status_highlight()
150 | ```
151 |
152 | ## API
153 |
154 | ### Core Functions
155 |
156 | ```lua
157 | -- Initialize the plugin
158 | require('ziit').setup(config)
159 |
160 | -- Manual heartbeat
161 | require('ziit').send_heartbeat()
162 |
163 | -- Get status
164 | local status = require('ziit').get_status()
165 | -- Returns: { enabled = bool, queue_size = number, last_heartbeat = table }
166 |
167 | -- Get stats
168 | require('ziit').get_stats(function(success, stats)
169 | if success then
170 | -- check https://docs.ziit.app/api/stats for the schema of the result
171 | end
172 | end)
173 |
174 | -- Test connection
175 | require('ziit').test_connection(function(success, message)
176 | print('Connection: ' .. (success and 'OK' or 'Failed'))
177 | end)
178 |
179 | -- Debug control
180 | require('ziit').enable_debug() -- Turn on debug mode
181 | require('ziit').disable_debug() -- Turn off debug mode
182 | local is_debug = require('ziit').toggle_debug() -- Toggle and return new state
183 | ```
184 |
185 | ### Status Functions
186 |
187 | ```lua
188 | local status = require('ziit.status')
189 |
190 | -- Get formatted status text
191 | local text = status.get_status_text()
192 |
193 | -- Get appropriate highlight group
194 | local highlight = status.get_status_highlight()
195 |
196 | -- Refresh cached status
197 | status.refresh()
198 | ```
199 |
200 | ## Troubleshooting
201 |
202 | ### Enable Debug Mode
203 |
204 | ```lua
205 | require('ziit').setup({ debug = true })
206 | ```
207 |
208 | Or temporarily:
209 |
210 | ```vim
211 | :lua require('ziit.config').set('debug', true)
212 | ```
213 |
214 | ### Common Issues
215 |
216 | **Plugin not tracking:**
217 |
218 | - Verify API key with `:ZiitTest`
219 | - Check status with `:checkhealth ziit`
220 | - Ensure file isn't in exclude patterns
221 |
222 | **Heartbeats not reaching server:**
223 |
224 | - Check internet connection
225 | - Verify server URL is correct
226 | - Heartbeats are queued offline and sync automatically
227 |
228 | **High queue size:**
229 |
230 | - Indicates network/server issues
231 | - Heartbeats sync automatically when connection restored
232 | - Old heartbeats (>24h) are auto-purged
233 |
234 | ## How It Works
235 |
236 | 1. **Hybrid Tracking**: Combines timer-based (2 minutes) and activity-based heartbeats
237 | 2. **Rate Limiting**: Prevents spam with minimum 10-second intervals between heartbeats
238 | 3. **Heartbeat Creation**: Collects file path, language, project, branch, and timestamp
239 | 4. **Current File Detection**: Only sends heartbeats when actively working on a file
240 | 5. **Offline Queue**: Stores heartbeats when offline, syncs when connection restored
241 | 6. **Data Cleanup**: Automatically purges old queued heartbeats
242 |
243 | ## Contributing
244 |
245 | Contributions welcome! Please read the contributing guidelines and submit pull requests.
246 |
247 | ## License
248 |
249 | [AGPL-3.0 License](LICENSE)
250 |
--------------------------------------------------------------------------------
/lua/ziit/init.lua:
--------------------------------------------------------------------------------
1 | local M = {}
2 |
3 | local last_heartbeat = nil
4 | local heartbeat_timer = nil
5 | local is_initialized = false
6 |
7 | local function send_heartbeat()
8 | local config = require('ziit.config')
9 |
10 | if not config.is_enabled() then
11 | return
12 | end
13 |
14 | local heartbeat = require('ziit.heartbeat')
15 | local new_heartbeat = heartbeat.create()
16 |
17 | if not new_heartbeat then
18 | return
19 | end
20 |
21 | -- Rate limiting: don't send if we just sent a heartbeat recently
22 | if last_heartbeat and last_heartbeat.timestamp then
23 | local last_time = last_heartbeat.timestamp
24 | local current_time = os.time()
25 |
26 | -- Parse ISO timestamp to seconds
27 | local last_timestamp = os.time({
28 | year = tonumber(last_time:sub(1, 4)),
29 | month = tonumber(last_time:sub(6, 7)),
30 | day = tonumber(last_time:sub(9, 10)),
31 | hour = tonumber(last_time:sub(12, 13)),
32 | min = tonumber(last_time:sub(15, 16)),
33 | sec = tonumber(last_time:sub(18, 19)),
34 | })
35 |
36 | -- Minimum 10 seconds between heartbeats
37 | if (current_time - last_timestamp) < 10 then
38 | return
39 | end
40 | end
41 |
42 | last_heartbeat = new_heartbeat
43 |
44 | local http = require('ziit.http')
45 | local queue = require('ziit.queue')
46 |
47 | http.send_heartbeat(new_heartbeat, function(success)
48 | if not success then
49 | queue.add(new_heartbeat)
50 |
51 | if config.is_debug() then
52 | vim.notify('Ziit: Heartbeat queued for later sync', vim.log.levels.DEBUG)
53 | end
54 | elseif config.is_debug() then
55 | vim.notify('Ziit: Heartbeat sent successfully', vim.log.levels.DEBUG)
56 | end
57 | end)
58 | end
59 |
60 | local function start_heartbeat_timer()
61 | local config = require('ziit.config')
62 | local interval = config.get('heartbeat_interval')
63 |
64 | if not interval or interval <= 0 then
65 | return
66 | end
67 |
68 | -- Stop existing timer if running
69 | if heartbeat_timer then
70 | heartbeat_timer:stop()
71 | heartbeat_timer:close()
72 | heartbeat_timer = nil
73 | end
74 |
75 | heartbeat_timer = vim.loop.new_timer()
76 | if heartbeat_timer then
77 | -- Start immediately, then repeat every interval
78 | heartbeat_timer:start(
79 | 0,
80 | interval * 1000,
81 | vim.schedule_wrap(function()
82 | send_heartbeat()
83 | end)
84 | )
85 |
86 | if config.is_debug() then
87 | vim.notify('Ziit: Started heartbeat timer (interval: ' .. interval .. 's)', vim.log.levels.INFO)
88 | end
89 | end
90 | end
91 |
92 | local function stop_heartbeat_timer()
93 | if heartbeat_timer then
94 | heartbeat_timer:stop()
95 | heartbeat_timer:close()
96 | heartbeat_timer = nil
97 |
98 | local config = require('ziit.config')
99 | if config.is_debug() then
100 | vim.notify('Ziit: Stopped heartbeat timer', vim.log.levels.INFO)
101 | end
102 | end
103 | end
104 |
105 | local function setup_autocmds()
106 | local group = vim.api.nvim_create_augroup('Ziit', { clear = true })
107 |
108 | -- Activity-based events that trigger immediate heartbeats
109 | local events = {
110 | 'BufEnter',
111 | 'BufWinEnter',
112 | 'CursorMoved',
113 | 'CursorMovedI',
114 | 'TextChanged',
115 | 'TextChangedI',
116 | 'InsertEnter',
117 | 'InsertLeave',
118 | }
119 |
120 | vim.api.nvim_create_autocmd(events, {
121 | group = group,
122 | callback = function()
123 | -- Send heartbeat immediately on activity
124 | send_heartbeat()
125 | end,
126 | desc = 'Send Ziit heartbeat on activity',
127 | })
128 |
129 | vim.api.nvim_create_autocmd('VimLeavePre', {
130 | group = group,
131 | callback = function()
132 | stop_heartbeat_timer()
133 | local queue = require('ziit.queue')
134 | queue.sync()
135 | end,
136 | desc = 'Stop Ziit timer and sync queue on exit',
137 | })
138 | end
139 |
140 | local function setup_commands()
141 | vim.api.nvim_create_user_command('ZiitEnable', function()
142 | local config = require('ziit.config')
143 | config.set('enabled', true)
144 | start_heartbeat_timer()
145 | vim.notify('Ziit: Enabled', vim.log.levels.INFO)
146 | end, { desc = 'Enable Ziit tracking' })
147 |
148 | vim.api.nvim_create_user_command('ZiitDisable', function()
149 | local config = require('ziit.config')
150 | config.set('enabled', false)
151 | stop_heartbeat_timer()
152 | vim.notify('Ziit: Disabled', vim.log.levels.INFO)
153 | end, { desc = 'Disable Ziit tracking' })
154 |
155 | vim.api.nvim_create_user_command('ZiitSync', function()
156 | local queue = require('ziit.queue')
157 |
158 | if queue.is_empty() then
159 | vim.notify('Ziit: No heartbeats to sync', vim.log.levels.INFO)
160 | return
161 | end
162 |
163 | vim.notify('Ziit: Syncing heartbeats...', vim.log.levels.INFO)
164 | queue.sync()
165 | end, { desc = 'Sync queued heartbeats' })
166 |
167 | vim.api.nvim_create_user_command('ZiitTest', function()
168 | local http = require('ziit.http')
169 |
170 | vim.notify('Ziit: Testing connection...', vim.log.levels.INFO)
171 | http.test_connection(function(success, message)
172 | vim.notify('Ziit: ' .. message, success and vim.log.levels.INFO or vim.log.levels.ERROR)
173 | end)
174 | end, { desc = 'Test Ziit connection' })
175 |
176 | vim.api.nvim_create_user_command('ZiitStats', function()
177 | M.get_stats(function(success, stats)
178 | if success and stats then
179 | local message = string.format('Today: %s, This week: %s', stats.today or 'N/A', stats.week or 'N/A')
180 | vim.notify('Ziit: ' .. message, vim.log.levels.INFO)
181 | else
182 | vim.notify('Ziit: Failed to fetch stats', vim.log.levels.ERROR)
183 | end
184 | end)
185 | end, { desc = 'Show Ziit stats' })
186 |
187 | vim.api.nvim_create_user_command('ZiitClearQueue', function()
188 | local queue = require('ziit.queue')
189 | queue.clear()
190 | vim.notify('Ziit: Queue cleared', vim.log.levels.INFO)
191 | end, { desc = 'Clear heartbeat queue' })
192 |
193 | vim.api.nvim_create_user_command('ZiitDebugOn', function()
194 | M.enable_debug()
195 | end, { desc = 'Enable debug mode' })
196 |
197 | vim.api.nvim_create_user_command('ZiitDebugOff', function()
198 | M.disable_debug()
199 | end, { desc = 'Disable debug mode' })
200 |
201 | vim.api.nvim_create_user_command('ZiitDebugToggle', function()
202 | M.toggle_debug()
203 | end, { desc = 'Toggle debug mode' })
204 | end
205 |
206 | function M.setup(user_config)
207 | if is_initialized then
208 | return
209 | end
210 |
211 | local config = require('ziit.config')
212 | config.setup(user_config)
213 |
214 | if not config.is_enabled() then
215 | if config.is_debug() then
216 | vim.notify('Ziit: Plugin disabled or not configured', vim.log.levels.INFO)
217 | end
218 | return
219 | end
220 |
221 | local queue = require('ziit.queue')
222 | queue.init()
223 | queue.start_sync_timer()
224 |
225 | setup_autocmds()
226 | setup_commands()
227 |
228 | -- Start the heartbeat timer
229 | start_heartbeat_timer()
230 |
231 | is_initialized = true
232 |
233 | if config.is_debug() then
234 | vim.notify('Ziit: Plugin initialized', vim.log.levels.INFO)
235 | end
236 | end
237 |
238 | function M.send_heartbeat()
239 | send_heartbeat()
240 | end
241 |
242 | function M.get_status()
243 | local config = require('ziit.config')
244 | local queue = require('ziit.queue')
245 |
246 | return {
247 | enabled = config.is_enabled(),
248 | queue_size = queue.size(),
249 | last_heartbeat = last_heartbeat,
250 | }
251 | end
252 |
253 | function M.get_stats(callback)
254 | local http = require('ziit.http')
255 | http.get_stats(callback)
256 | end
257 |
258 | function M.test_connection(callback)
259 | local http = require('ziit.http')
260 | http.test_connection(callback)
261 | end
262 |
263 | function M.enable_debug()
264 | local config = require('ziit.config')
265 | config.set('debug', true)
266 | vim.notify('Ziit: Debug mode enabled', vim.log.levels.INFO)
267 | end
268 |
269 | function M.disable_debug()
270 | local config = require('ziit.config')
271 | config.set('debug', false)
272 | vim.notify('Ziit: Debug mode disabled', vim.log.levels.INFO)
273 | end
274 |
275 | function M.toggle_debug()
276 | local config = require('ziit.config')
277 | local current_debug = config.get('debug')
278 | config.set('debug', not current_debug)
279 | vim.notify('Ziit: Debug mode ' .. (current_debug and 'disabled' or 'enabled'), vim.log.levels.INFO)
280 | return not current_debug
281 | end
282 |
283 | return M
284 |
--------------------------------------------------------------------------------
/doc/ziit.txt:
--------------------------------------------------------------------------------
1 | *ziit.txt* Ziit Time Tracking for Neovim
2 |
3 | ZIIT *ziit* *ziit.nvim*
4 |
5 | A Neovim plugin for tracking coding time and activity with Ziit.
6 |
7 | ==============================================================================
8 | CONTENTS *ziit-contents*
9 |
10 | 1. Introduction ..................... |ziit-introduction|
11 | 2. Requirements ..................... |ziit-requirements|
12 | 3. Installation ..................... |ziit-installation|
13 | 4. Configuration .................... |ziit-configuration|
14 | 5. Commands ......................... |ziit-commands|
15 | 6. API .............................. |ziit-api|
16 | 7. Troubleshooting .................. |ziit-troubleshooting|
17 |
18 | ==============================================================================
19 | 1. INTRODUCTION *ziit-introduction*
20 |
21 | Ziit.nvim is a Neovim plugin that automatically tracks your coding activity
22 | by sending heartbeats to your Ziit server instance at regular intervals.
23 | It provides seamless integration with the Ziit time tracking ecosystem.
24 |
25 | Features:~
26 | - Timer-based heartbeat tracking (2 minutes default)
27 | - Offline queue management for unreliable connections
28 | - Status bar integration
29 | - Configurable tracking intervals and exclusions
30 | - Project and language detection
31 | - Git branch tracking
32 |
33 | ==============================================================================
34 | 2. REQUIREMENTS *ziit-requirements*
35 |
36 | - Neovim 0.7+
37 | - plenary.nvim (https://github.com/nvim-lua/plenary.nvim)
38 | - A Ziit server instance and API key
39 |
40 | ==============================================================================
41 | 3. INSTALLATION *ziit-installation*
42 |
43 | Using lazy.nvim:~
44 | >lua
45 | {
46 | 'your-username/ziit-neovim',
47 | dependencies = { 'nvim-lua/plenary.nvim' },
48 | config = function()
49 | require('ziit').setup({
50 | api_key = 'your-api-key',
51 | base_url = 'https://your-ziit-instance.com' -- optional
52 | })
53 | end
54 | }
55 | <
56 |
57 | Using packer.nvim:~
58 | >lua
59 | use {
60 | 'your-username/ziit-neovim',
61 | requires = { 'nvim-lua/plenary.nvim' },
62 | config = function()
63 | require('ziit').setup({
64 | api_key = 'your-api-key'
65 | })
66 | end
67 | }
68 | <
69 |
70 | ==============================================================================
71 | 4. CONFIGURATION *ziit-configuration*
72 |
73 | Configuration can be provided in several ways (in order of priority):
74 |
75 | 1. Lua configuration via setup() function
76 | 2. Global variable `vim.g.ziit_config`
77 | 3. Project-specific `.ziit.json` file
78 | 4. User home directory `~/.ziit.json` file
79 | 5. Environment variables (lowest priority)
80 |
81 | Configuration Options:~
82 |
83 | `base_url` (string) Ziit server URL (default: 'https://ziit.app')
84 | `api_key` (string) Your Ziit API key (required)
85 | `enabled` (boolean) Enable/disable tracking (default: true)
86 | `debug` (boolean) Enable debug logging (default: false)
87 | `heartbeat_interval` (number) Minimum seconds between heartbeats (default: 120)
88 | `offline_sync_interval` (number) Seconds between offline sync attempts (default: 300)
89 | `max_heartbeat_age` (number) Maximum age of queued heartbeats in seconds (default: 86400)
90 | `use_absolute_paths` (boolean) Use absolute file paths (default: true)
91 | `exclude_patterns` (table) Patterns to exclude from tracking
92 |
93 | Example configuration:~
94 | >lua
95 | require('ziit').setup({
96 | api_key = 'your-api-key-here',
97 | base_url = 'https://ziit.app',
98 | enabled = true,
99 | debug = false,
100 | heartbeat_interval = 120,
101 | exclude_patterns = {
102 | '%.git/',
103 | 'node_modules/',
104 | '%.tmp$',
105 | }
106 | })
107 | <
108 |
109 | JSON configuration file example (~/.ziit.json):~
110 | >json
111 | {
112 | "api_key": "your-api-key-here",
113 | "base_url": "https://ziit.app",
114 | "enabled": true,
115 | "debug": false
116 | }
117 | <
118 |
119 | Environment variables:~
120 | >bash
121 | export ZIIT_API_KEY="your-api-key-here"
122 | export ZIIT_BASE_URL="https://ziit.app"
123 | export ZIIT_ENABLED="true"
124 | export ZIIT_DEBUG="false"
125 | <
126 |
127 | ==============================================================================
128 | 5. COMMANDS *ziit-commands*
129 |
130 | :ZiitSetup [options] *:ZiitSetup*
131 | Initialize the plugin with optional configuration parameters.
132 |
133 | Examples:~
134 | >
135 | :ZiitSetup
136 | :ZiitSetup api_key=your-key enabled=true debug=false
137 | <
138 |
139 | :ZiitEnable *:ZiitEnable*
140 | Enable Ziit tracking.
141 |
142 | :ZiitDisable *:ZiitDisable*
143 | Disable Ziit tracking.
144 |
145 | :checkhealth ziit *:checkhealth-ziit*
146 | Check plugin health, configuration, and connection status.
147 | Comprehensive diagnostic information including dependencies,
148 | configuration validation, and connection testing.
149 |
150 | :ZiitSync *:ZiitSync*
151 | Manually sync queued heartbeats to the server.
152 |
153 | :ZiitTest *:ZiitTest*
154 | Test connection to the Ziit server.
155 |
156 | :ZiitStats *:ZiitStats*
157 | Fetch and display today's coding statistics.
158 |
159 | :ZiitClearQueue *:ZiitClearQueue*
160 | Clear the offline heartbeat queue.
161 |
162 | :ZiitDebugOn *:ZiitDebugOn*
163 | Enable debug mode for verbose logging.
164 |
165 | :ZiitDebugOff *:ZiitDebugOff*
166 | Disable debug mode.
167 |
168 | :ZiitDebugToggle *:ZiitDebugToggle*
169 | Toggle debug mode on/off.
170 |
171 | ==============================================================================
172 | 6. API *ziit-api*
173 |
174 | The plugin exposes a Lua API for advanced usage:
175 |
176 | require('ziit').setup(config) *ziit.setup()*
177 | Initialize the plugin with the given configuration.
178 |
179 | Parameters:~
180 | {config} (table) Configuration options
181 |
182 | require('ziit').send_heartbeat() *ziit.send_heartbeat()*
183 | Manually send a heartbeat.
184 |
185 | require('ziit').get_status() *ziit.get_status()*
186 | Get current plugin status.
187 |
188 | Returns:~
189 | {table} Status information containing:
190 | - enabled: boolean
191 | - queue_size: number
192 | - last_heartbeat: table|nil
193 |
194 | require('ziit').get_stats(callback) *ziit.get_stats()*
195 | Get coding statistics from the Ziit server.
196 |
197 | Parameters:~
198 | {callback} function(success, stats) - Called with results
199 |
200 | Example:~
201 | >lua
202 | require('ziit').get_stats(function(success, stats)
203 | if success then
204 | print('Today: ' .. (stats.today or 'N/A'))
205 | end
206 | end)
207 | <
208 |
209 | require('ziit').test_connection(callback) *ziit.test_connection()*
210 | Test connection to the Ziit server.
211 |
212 | Parameters:~
213 | {callback} function(success, message) - Called with results
214 |
215 | require('ziit').enable_debug() *ziit.enable_debug()*
216 | Enable debug mode for verbose logging.
217 |
218 | require('ziit').disable_debug() *ziit.disable_debug()*
219 | Disable debug mode.
220 |
221 | require('ziit').toggle_debug() *ziit.toggle_debug()*
222 | Toggle debug mode on/off.
223 |
224 | Returns:~
225 | {boolean} New debug state (true if enabled, false if disabled)
226 |
227 | Status Bar Integration:~
228 |
229 | For lualine users, the plugin automatically integrates with your statusline.
230 | For custom statuslines, use:
231 | >lua
232 | require('ziit.status').get_status_text()
233 | require('ziit.status').get_status_highlight()
234 | <
235 |
236 | ==============================================================================
237 | 7. TROUBLESHOOTING *ziit-troubleshooting*
238 |
239 | Common Issues:~
240 |
241 | Plugin not tracking activity:~
242 | - Check that you have a valid API key configured
243 | - Ensure the plugin is enabled with `:ZiitStatus`
244 | - Test the connection with `:ZiitTest`
245 | - Enable debug mode to see detailed logging
246 |
247 | Heartbeats not reaching the server:~
248 | - Check your internet connection
249 | - Verify your Ziit server URL is correct
250 | - Heartbeats are queued offline and will sync when connection is restored
251 | - Use `:ZiitSync` to manually trigger sync
252 |
253 | High queue size:~
254 | - This indicates network issues or server problems
255 | - Heartbeats will be automatically synced when connection is restored
256 | - Old heartbeats (>24 hours by default) are automatically purged
257 |
258 | Debug Mode:~
259 | Enable debug mode for detailed logging:
260 | >lua
261 | require('ziit').setup({ debug = true })
262 | <
263 |
264 | or temporarily:
265 | >
266 | :lua require('ziit.config').set('debug', true)
267 | <
268 |
269 | Support:~
270 | For issues and feature requests, visit:
271 | https://github.com/your-username/ziit-neovim
272 |
273 | ==============================================================================
274 | vim:tw=78:ts=8:ft=help:norl:
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | GNU AFFERO GENERAL PUBLIC LICENSE
2 | Version 3, 19 November 2007
3 |
4 | Copyright (C) 2007 Free Software Foundation, Inc.
5 | Everyone is permitted to copy and distribute verbatim copies
6 | of this license document, but changing it is not allowed.
7 |
8 | Preamble
9 |
10 | The GNU Affero General Public License is a free, copyleft license for
11 | software and other kinds of works, specifically designed to ensure
12 | cooperation with the community in the case of network server software.
13 |
14 | The licenses for most software and other practical works are designed
15 | to take away your freedom to share and change the works. By contrast,
16 | our General Public Licenses are intended to guarantee your freedom to
17 | share and change all versions of a program--to make sure it remains free
18 | software for all its users.
19 |
20 | When we speak of free software, we are referring to freedom, not
21 | price. Our General Public Licenses are designed to make sure that you
22 | have the freedom to distribute copies of free software (and charge for
23 | them if you wish), that you receive source code or can get it if you
24 | want it, that you can change the software or use pieces of it in new
25 | free programs, and that you know you can do these things.
26 |
27 | Developers that use our General Public Licenses protect your rights
28 | with two steps: (1) assert copyright on the software, and (2) offer
29 | you this License which gives you legal permission to copy, distribute
30 | and/or modify the software.
31 |
32 | A secondary benefit of defending all users' freedom is that
33 | improvements made in alternate versions of the program, if they
34 | receive widespread use, become available for other developers to
35 | incorporate. Many developers of free software are heartened and
36 | encouraged by the resulting cooperation. However, in the case of
37 | software used on network servers, this result may fail to come about.
38 | The GNU General Public License permits making a modified version and
39 | letting the public access it on a server without ever releasing its
40 | source code to the public.
41 |
42 | The GNU Affero General Public License is designed specifically to
43 | ensure that, in such cases, the modified source code becomes available
44 | to the community. It requires the operator of a network server to
45 | provide the source code of the modified version running there to the
46 | users of that server. Therefore, public use of a modified version, on
47 | a publicly accessible server, gives the public access to the source
48 | code of the modified version.
49 |
50 | An older license, called the Affero General Public License and
51 | published by Affero, was designed to accomplish similar goals. This is
52 | a different license, not a version of the Affero GPL, but Affero has
53 | released a new version of the Affero GPL which permits relicensing under
54 | this license.
55 |
56 | The precise terms and conditions for copying, distribution and
57 | modification follow.
58 |
59 | TERMS AND CONDITIONS
60 |
61 | 0. Definitions.
62 |
63 | "This License" refers to version 3 of the GNU Affero General Public License.
64 |
65 | "Copyright" also means copyright-like laws that apply to other kinds of
66 | works, such as semiconductor masks.
67 |
68 | "The Program" refers to any copyrightable work licensed under this
69 | License. Each licensee is addressed as "you". "Licensees" and
70 | "recipients" may be individuals or organizations.
71 |
72 | To "modify" a work means to copy from or adapt all or part of the work
73 | in a fashion requiring copyright permission, other than the making of an
74 | exact copy. The resulting work is called a "modified version" of the
75 | earlier work or a work "based on" the earlier work.
76 |
77 | A "covered work" means either the unmodified Program or a work based
78 | on the Program.
79 |
80 | To "propagate" a work means to do anything with it that, without
81 | permission, would make you directly or secondarily liable for
82 | infringement under applicable copyright law, except executing it on a
83 | computer or modifying a private copy. Propagation includes copying,
84 | distribution (with or without modification), making available to the
85 | public, and in some countries other activities as well.
86 |
87 | To "convey" a work means any kind of propagation that enables other
88 | parties to make or receive copies. Mere interaction with a user through
89 | a computer network, with no transfer of a copy, is not conveying.
90 |
91 | An interactive user interface displays "Appropriate Legal Notices"
92 | to the extent that it includes a convenient and prominently visible
93 | feature that (1) displays an appropriate copyright notice, and (2)
94 | tells the user that there is no warranty for the work (except to the
95 | extent that warranties are provided), that licensees may convey the
96 | work under this License, and how to view a copy of this License. If
97 | the interface presents a list of user commands or options, such as a
98 | menu, a prominent item in the list meets this criterion.
99 |
100 | 1. Source Code.
101 |
102 | The "source code" for a work means the preferred form of the work
103 | for making modifications to it. "Object code" means any non-source
104 | form of a work.
105 |
106 | A "Standard Interface" means an interface that either is an official
107 | standard defined by a recognized standards body, or, in the case of
108 | interfaces specified for a particular programming language, one that
109 | is widely used among developers working in that language.
110 |
111 | The "System Libraries" of an executable work include anything, other
112 | than the work as a whole, that (a) is included in the normal form of
113 | packaging a Major Component, but which is not part of that Major
114 | Component, and (b) serves only to enable use of the work with that
115 | Major Component, or to implement a Standard Interface for which an
116 | implementation is available to the public in source code form. A
117 | "Major Component", in this context, means a major essential component
118 | (kernel, window system, and so on) of the specific operating system
119 | (if any) on which the executable work runs, or a compiler used to
120 | produce the work, or an object code interpreter used to run it.
121 |
122 | The "Corresponding Source" for a work in object code form means all
123 | the source code needed to generate, install, and (for an executable
124 | work) run the object code and to modify the work, including scripts to
125 | control those activities. However, it does not include the work's
126 | System Libraries, or general-purpose tools or generally available free
127 | programs which are used unmodified in performing those activities but
128 | which are not part of the work. For example, Corresponding Source
129 | includes interface definition files associated with source files for
130 | the work, and the source code for shared libraries and dynamically
131 | linked subprograms that the work is specifically designed to require,
132 | such as by intimate data communication or control flow between those
133 | subprograms and other parts of the work.
134 |
135 | The Corresponding Source need not include anything that users
136 | can regenerate automatically from other parts of the Corresponding
137 | Source.
138 |
139 | The Corresponding Source for a work in source code form is that
140 | same work.
141 |
142 | 2. Basic Permissions.
143 |
144 | All rights granted under this License are granted for the term of
145 | copyright on the Program, and are irrevocable provided the stated
146 | conditions are met. This License explicitly affirms your unlimited
147 | permission to run the unmodified Program. The output from running a
148 | covered work is covered by this License only if the output, given its
149 | content, constitutes a covered work. This License acknowledges your
150 | rights of fair use or other equivalent, as provided by copyright law.
151 |
152 | You may make, run and propagate covered works that you do not
153 | convey, without conditions so long as your license otherwise remains
154 | in force. You may convey covered works to others for the sole purpose
155 | of having them make modifications exclusively for you, or provide you
156 | with facilities for running those works, provided that you comply with
157 | the terms of this License in conveying all material for which you do
158 | not control copyright. Those thus making or running the covered works
159 | for you must do so exclusively on your behalf, under your direction
160 | and control, on terms that prohibit them from making any copies of
161 | your copyrighted material outside their relationship with you.
162 |
163 | Conveying under any other circumstances is permitted solely under
164 | the conditions stated below. Sublicensing is not allowed; section 10
165 | makes it unnecessary.
166 |
167 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
168 |
169 | No covered work shall be deemed part of an effective technological
170 | measure under any applicable law fulfilling obligations under article
171 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or
172 | similar laws prohibiting or restricting circumvention of such
173 | measures.
174 |
175 | When you convey a covered work, you waive any legal power to forbid
176 | circumvention of technological measures to the extent such circumvention
177 | is effected by exercising rights under this License with respect to
178 | the covered work, and you disclaim any intention to limit operation or
179 | modification of the work as a means of enforcing, against the work's
180 | users, your or third parties' legal rights to forbid circumvention of
181 | technological measures.
182 |
183 | 4. Conveying Verbatim Copies.
184 |
185 | You may convey verbatim copies of the Program's source code as you
186 | receive it, in any medium, provided that you conspicuously and
187 | appropriately publish on each copy an appropriate copyright notice;
188 | keep intact all notices stating that this License and any
189 | non-permissive terms added in accord with section 7 apply to the code;
190 | keep intact all notices of the absence of any warranty; and give all
191 | recipients a copy of this License along with the Program.
192 |
193 | You may charge any price or no price for each copy that you convey,
194 | and you may offer support or warranty protection for a fee.
195 |
196 | 5. Conveying Modified Source Versions.
197 |
198 | You may convey a work based on the Program, or the modifications to
199 | produce it from the Program, in the form of source code under the
200 | terms of section 4, provided that you also meet all of these conditions:
201 |
202 | a) The work must carry prominent notices stating that you modified
203 | it, and giving a relevant date.
204 |
205 | b) The work must carry prominent notices stating that it is
206 | released under this License and any conditions added under section
207 | 7. This requirement modifies the requirement in section 4 to
208 | "keep intact all notices".
209 |
210 | c) You must license the entire work, as a whole, under this
211 | License to anyone who comes into possession of a copy. This
212 | License will therefore apply, along with any applicable section 7
213 | additional terms, to the whole of the work, and all its parts,
214 | regardless of how they are packaged. This License gives no
215 | permission to license the work in any other way, but it does not
216 | invalidate such permission if you have separately received it.
217 |
218 | d) If the work has interactive user interfaces, each must display
219 | Appropriate Legal Notices; however, if the Program has interactive
220 | interfaces that do not display Appropriate Legal Notices, your
221 | work need not make them do so.
222 |
223 | A compilation of a covered work with other separate and independent
224 | works, which are not by their nature extensions of the covered work,
225 | and which are not combined with it such as to form a larger program,
226 | in or on a volume of a storage or distribution medium, is called an
227 | "aggregate" if the compilation and its resulting copyright are not
228 | used to limit the access or legal rights of the compilation's users
229 | beyond what the individual works permit. Inclusion of a covered work
230 | in an aggregate does not cause this License to apply to the other
231 | parts of the aggregate.
232 |
233 | 6. Conveying Non-Source Forms.
234 |
235 | You may convey a covered work in object code form under the terms
236 | of sections 4 and 5, provided that you also convey the
237 | machine-readable Corresponding Source under the terms of this License,
238 | in one of these ways:
239 |
240 | a) Convey the object code in, or embodied in, a physical product
241 | (including a physical distribution medium), accompanied by the
242 | Corresponding Source fixed on a durable physical medium
243 | customarily used for software interchange.
244 |
245 | b) Convey the object code in, or embodied in, a physical product
246 | (including a physical distribution medium), accompanied by a
247 | written offer, valid for at least three years and valid for as
248 | long as you offer spare parts or customer support for that product
249 | model, to give anyone who possesses the object code either (1) a
250 | copy of the Corresponding Source for all the software in the
251 | product that is covered by this License, on a durable physical
252 | medium customarily used for software interchange, for a price no
253 | more than your reasonable cost of physically performing this
254 | conveying of source, or (2) access to copy the
255 | Corresponding Source from a network server at no charge.
256 |
257 | c) Convey individual copies of the object code with a copy of the
258 | written offer to provide the Corresponding Source. This
259 | alternative is allowed only occasionally and noncommercially, and
260 | only if you received the object code with such an offer, in accord
261 | with subsection 6b.
262 |
263 | d) Convey the object code by offering access from a designated
264 | place (gratis or for a charge), and offer equivalent access to the
265 | Corresponding Source in the same way through the same place at no
266 | further charge. You need not require recipients to copy the
267 | Corresponding Source along with the object code. If the place to
268 | copy the object code is a network server, the Corresponding Source
269 | may be on a different server (operated by you or a third party)
270 | that supports equivalent copying facilities, provided you maintain
271 | clear directions next to the object code saying where to find the
272 | Corresponding Source. Regardless of what server hosts the
273 | Corresponding Source, you remain obligated to ensure that it is
274 | available for as long as needed to satisfy these requirements.
275 |
276 | e) Convey the object code using peer-to-peer transmission, provided
277 | you inform other peers where the object code and Corresponding
278 | Source of the work are being offered to the general public at no
279 | charge under subsection 6d.
280 |
281 | A separable portion of the object code, whose source code is excluded
282 | from the Corresponding Source as a System Library, need not be
283 | included in conveying the object code work.
284 |
285 | A "User Product" is either (1) a "consumer product", which means any
286 | tangible personal property which is normally used for personal, family,
287 | or household purposes, or (2) anything designed or sold for incorporation
288 | into a dwelling. In determining whether a product is a consumer product,
289 | doubtful cases shall be resolved in favor of coverage. For a particular
290 | product received by a particular user, "normally used" refers to a
291 | typical or common use of that class of product, regardless of the status
292 | of the particular user or of the way in which the particular user
293 | actually uses, or expects or is expected to use, the product. A product
294 | is a consumer product regardless of whether the product has substantial
295 | commercial, industrial or non-consumer uses, unless such uses represent
296 | the only significant mode of use of the product.
297 |
298 | "Installation Information" for a User Product means any methods,
299 | procedures, authorization keys, or other information required to install
300 | and execute modified versions of a covered work in that User Product from
301 | a modified version of its Corresponding Source. The information must
302 | suffice to ensure that the continued functioning of the modified object
303 | code is in no case prevented or interfered with solely because
304 | modification has been made.
305 |
306 | If you convey an object code work under this section in, or with, or
307 | specifically for use in, a User Product, and the conveying occurs as
308 | part of a transaction in which the right of possession and use of the
309 | User Product is transferred to the recipient in perpetuity or for a
310 | fixed term (regardless of how the transaction is characterized), the
311 | Corresponding Source conveyed under this section must be accompanied
312 | by the Installation Information. But this requirement does not apply
313 | if neither you nor any third party retains the ability to install
314 | modified object code on the User Product (for example, the work has
315 | been installed in ROM).
316 |
317 | The requirement to provide Installation Information does not include a
318 | requirement to continue to provide support service, warranty, or updates
319 | for a work that has been modified or installed by the recipient, or for
320 | the User Product in which it has been modified or installed. Access to a
321 | network may be denied when the modification itself materially and
322 | adversely affects the operation of the network or violates the rules and
323 | protocols for communication across the network.
324 |
325 | Corresponding Source conveyed, and Installation Information provided,
326 | in accord with this section must be in a format that is publicly
327 | documented (and with an implementation available to the public in
328 | source code form), and must require no special password or key for
329 | unpacking, reading or copying.
330 |
331 | 7. Additional Terms.
332 |
333 | "Additional permissions" are terms that supplement the terms of this
334 | License by making exceptions from one or more of its conditions.
335 | Additional permissions that are applicable to the entire Program shall
336 | be treated as though they were included in this License, to the extent
337 | that they are valid under applicable law. If additional permissions
338 | apply only to part of the Program, that part may be used separately
339 | under those permissions, but the entire Program remains governed by
340 | this License without regard to the additional permissions.
341 |
342 | When you convey a copy of a covered work, you may at your option
343 | remove any additional permissions from that copy, or from any part of
344 | it. (Additional permissions may be written to require their own
345 | removal in certain cases when you modify the work.) You may place
346 | additional permissions on material, added by you to a covered work,
347 | for which you have or can give appropriate copyright permission.
348 |
349 | Notwithstanding any other provision of this License, for material you
350 | add to a covered work, you may (if authorized by the copyright holders of
351 | that material) supplement the terms of this License with terms:
352 |
353 | a) Disclaiming warranty or limiting liability differently from the
354 | terms of sections 15 and 16 of this License; or
355 |
356 | b) Requiring preservation of specified reasonable legal notices or
357 | author attributions in that material or in the Appropriate Legal
358 | Notices displayed by works containing it; or
359 |
360 | c) Prohibiting misrepresentation of the origin of that material, or
361 | requiring that modified versions of such material be marked in
362 | reasonable ways as different from the original version; or
363 |
364 | d) Limiting the use for publicity purposes of names of licensors or
365 | authors of the material; or
366 |
367 | e) Declining to grant rights under trademark law for use of some
368 | trade names, trademarks, or service marks; or
369 |
370 | f) Requiring indemnification of licensors and authors of that
371 | material by anyone who conveys the material (or modified versions of
372 | it) with contractual assumptions of liability to the recipient, for
373 | any liability that these contractual assumptions directly impose on
374 | those licensors and authors.
375 |
376 | All other non-permissive additional terms are considered "further
377 | restrictions" within the meaning of section 10. If the Program as you
378 | received it, or any part of it, contains a notice stating that it is
379 | governed by this License along with a term that is a further
380 | restriction, you may remove that term. If a license document contains
381 | a further restriction but permits relicensing or conveying under this
382 | License, you may add to a covered work material governed by the terms
383 | of that license document, provided that the further restriction does
384 | not survive such relicensing or conveying.
385 |
386 | If you add terms to a covered work in accord with this section, you
387 | must place, in the relevant source files, a statement of the
388 | additional terms that apply to those files, or a notice indicating
389 | where to find the applicable terms.
390 |
391 | Additional terms, permissive or non-permissive, may be stated in the
392 | form of a separately written license, or stated as exceptions;
393 | the above requirements apply either way.
394 |
395 | 8. Termination.
396 |
397 | You may not propagate or modify a covered work except as expressly
398 | provided under this License. Any attempt otherwise to propagate or
399 | modify it is void, and will automatically terminate your rights under
400 | this License (including any patent licenses granted under the third
401 | paragraph of section 11).
402 |
403 | However, if you cease all violation of this License, then your
404 | license from a particular copyright holder is reinstated (a)
405 | provisionally, unless and until the copyright holder explicitly and
406 | finally terminates your license, and (b) permanently, if the copyright
407 | holder fails to notify you of the violation by some reasonable means
408 | prior to 60 days after the cessation.
409 |
410 | Moreover, your license from a particular copyright holder is
411 | reinstated permanently if the copyright holder notifies you of the
412 | violation by some reasonable means, this is the first time you have
413 | received notice of violation of this License (for any work) from that
414 | copyright holder, and you cure the violation prior to 30 days after
415 | your receipt of the notice.
416 |
417 | Termination of your rights under this section does not terminate the
418 | licenses of parties who have received copies or rights from you under
419 | this License. If your rights have been terminated and not permanently
420 | reinstated, you do not qualify to receive new licenses for the same
421 | material under section 10.
422 |
423 | 9. Acceptance Not Required for Having Copies.
424 |
425 | You are not required to accept this License in order to receive or
426 | run a copy of the Program. Ancillary propagation of a covered work
427 | occurring solely as a consequence of using peer-to-peer transmission
428 | to receive a copy likewise does not require acceptance. However,
429 | nothing other than this License grants you permission to propagate or
430 | modify any covered work. These actions infringe copyright if you do
431 | not accept this License. Therefore, by modifying or propagating a
432 | covered work, you indicate your acceptance of this License to do so.
433 |
434 | 10. Automatic Licensing of Downstream Recipients.
435 |
436 | Each time you convey a covered work, the recipient automatically
437 | receives a license from the original licensors, to run, modify and
438 | propagate that work, subject to this License. You are not responsible
439 | for enforcing compliance by third parties with this License.
440 |
441 | An "entity transaction" is a transaction transferring control of an
442 | organization, or substantially all assets of one, or subdividing an
443 | organization, or merging organizations. If propagation of a covered
444 | work results from an entity transaction, each party to that
445 | transaction who receives a copy of the work also receives whatever
446 | licenses to the work the party's predecessor in interest had or could
447 | give under the previous paragraph, plus a right to possession of the
448 | Corresponding Source of the work from the predecessor in interest, if
449 | the predecessor has it or can get it with reasonable efforts.
450 |
451 | You may not impose any further restrictions on the exercise of the
452 | rights granted or affirmed under this License. For example, you may
453 | not impose a license fee, royalty, or other charge for exercise of
454 | rights granted under this License, and you may not initiate litigation
455 | (including a cross-claim or counterclaim in a lawsuit) alleging that
456 | any patent claim is infringed by making, using, selling, offering for
457 | sale, or importing the Program or any portion of it.
458 |
459 | 11. Patents.
460 |
461 | A "contributor" is a copyright holder who authorizes use under this
462 | License of the Program or a work on which the Program is based. The
463 | work thus licensed is called the contributor's "contributor version".
464 |
465 | A contributor's "essential patent claims" are all patent claims
466 | owned or controlled by the contributor, whether already acquired or
467 | hereafter acquired, that would be infringed by some manner, permitted
468 | by this License, of making, using, or selling its contributor version,
469 | but do not include claims that would be infringed only as a
470 | consequence of further modification of the contributor version. For
471 | purposes of this definition, "control" includes the right to grant
472 | patent sublicenses in a manner consistent with the requirements of
473 | this License.
474 |
475 | Each contributor grants you a non-exclusive, worldwide, royalty-free
476 | patent license under the contributor's essential patent claims, to
477 | make, use, sell, offer for sale, import and otherwise run, modify and
478 | propagate the contents of its contributor version.
479 |
480 | In the following three paragraphs, a "patent license" is any express
481 | agreement or commitment, however denominated, not to enforce a patent
482 | (such as an express permission to practice a patent or covenant not to
483 | sue for patent infringement). To "grant" such a patent license to a
484 | party means to make such an agreement or commitment not to enforce a
485 | patent against the party.
486 |
487 | If you convey a covered work, knowingly relying on a patent license,
488 | and the Corresponding Source of the work is not available for anyone
489 | to copy, free of charge and under the terms of this License, through a
490 | publicly available network server or other readily accessible means,
491 | then you must either (1) cause the Corresponding Source to be so
492 | available, or (2) arrange to deprive yourself of the benefit of the
493 | patent license for this particular work, or (3) arrange, in a manner
494 | consistent with the requirements of this License, to extend the patent
495 | license to downstream recipients. "Knowingly relying" means you have
496 | actual knowledge that, but for the patent license, your conveying the
497 | covered work in a country, or your recipient's use of the covered work
498 | in a country, would infringe one or more identifiable patents in that
499 | country that you have reason to believe are valid.
500 |
501 | If, pursuant to or in connection with a single transaction or
502 | arrangement, you convey, or propagate by procuring conveyance of, a
503 | covered work, and grant a patent license to some of the parties
504 | receiving the covered work authorizing them to use, propagate, modify
505 | or convey a specific copy of the covered work, then the patent license
506 | you grant is automatically extended to all recipients of the covered
507 | work and works based on it.
508 |
509 | A patent license is "discriminatory" if it does not include within
510 | the scope of its coverage, prohibits the exercise of, or is
511 | conditioned on the non-exercise of one or more of the rights that are
512 | specifically granted under this License. You may not convey a covered
513 | work if you are a party to an arrangement with a third party that is
514 | in the business of distributing software, under which you make payment
515 | to the third party based on the extent of your activity of conveying
516 | the work, and under which the third party grants, to any of the
517 | parties who would receive the covered work from you, a discriminatory
518 | patent license (a) in connection with copies of the covered work
519 | conveyed by you (or copies made from those copies), or (b) primarily
520 | for and in connection with specific products or compilations that
521 | contain the covered work, unless you entered into that arrangement,
522 | or that patent license was granted, prior to 28 March 2007.
523 |
524 | Nothing in this License shall be construed as excluding or limiting
525 | any implied license or other defenses to infringement that may
526 | otherwise be available to you under applicable patent law.
527 |
528 | 12. No Surrender of Others' Freedom.
529 |
530 | If conditions are imposed on you (whether by court order, agreement or
531 | otherwise) that contradict the conditions of this License, they do not
532 | excuse you from the conditions of this License. If you cannot convey a
533 | covered work so as to satisfy simultaneously your obligations under this
534 | License and any other pertinent obligations, then as a consequence you may
535 | not convey it at all. For example, if you agree to terms that obligate you
536 | to collect a royalty for further conveying from those to whom you convey
537 | the Program, the only way you could satisfy both those terms and this
538 | License would be to refrain entirely from conveying the Program.
539 |
540 | 13. Remote Network Interaction; Use with the GNU General Public License.
541 |
542 | Notwithstanding any other provision of this License, if you modify the
543 | Program, your modified version must prominently offer all users
544 | interacting with it remotely through a computer network (if your version
545 | supports such interaction) an opportunity to receive the Corresponding
546 | Source of your version by providing access to the Corresponding Source
547 | from a network server at no charge, through some standard or customary
548 | means of facilitating copying of software. This Corresponding Source
549 | shall include the Corresponding Source for any work covered by version 3
550 | of the GNU General Public License that is incorporated pursuant to the
551 | following paragraph.
552 |
553 | Notwithstanding any other provision of this License, you have
554 | permission to link or combine any covered work with a work licensed
555 | under version 3 of the GNU General Public License into a single
556 | combined work, and to convey the resulting work. The terms of this
557 | License will continue to apply to the part which is the covered work,
558 | but the work with which it is combined will remain governed by version
559 | 3 of the GNU General Public License.
560 |
561 | 14. Revised Versions of this License.
562 |
563 | The Free Software Foundation may publish revised and/or new versions of
564 | the GNU Affero General Public License from time to time. Such new versions
565 | will be similar in spirit to the present version, but may differ in detail to
566 | address new problems or concerns.
567 |
568 | Each version is given a distinguishing version number. If the
569 | Program specifies that a certain numbered version of the GNU Affero General
570 | Public License "or any later version" applies to it, you have the
571 | option of following the terms and conditions either of that numbered
572 | version or of any later version published by the Free Software
573 | Foundation. If the Program does not specify a version number of the
574 | GNU Affero General Public License, you may choose any version ever published
575 | by the Free Software Foundation.
576 |
577 | If the Program specifies that a proxy can decide which future
578 | versions of the GNU Affero General Public License can be used, that proxy's
579 | public statement of acceptance of a version permanently authorizes you
580 | to choose that version for the Program.
581 |
582 | Later license versions may give you additional or different
583 | permissions. However, no additional obligations are imposed on any
584 | author or copyright holder as a result of your choosing to follow a
585 | later version.
586 |
587 | 15. Disclaimer of Warranty.
588 |
589 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
590 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
591 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
592 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
593 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
594 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
595 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
596 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
597 |
598 | 16. Limitation of Liability.
599 |
600 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
601 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
602 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
603 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
604 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
605 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
606 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
607 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
608 | SUCH DAMAGES.
609 |
610 | 17. Interpretation of Sections 15 and 16.
611 |
612 | If the disclaimer of warranty and limitation of liability provided
613 | above cannot be given local legal effect according to their terms,
614 | reviewing courts shall apply local law that most closely approximates
615 | an absolute waiver of all civil liability in connection with the
616 | Program, unless a warranty or assumption of liability accompanies a
617 | copy of the Program in return for a fee.
618 |
619 | END OF TERMS AND CONDITIONS
620 |
621 | How to Apply These Terms to Your New Programs
622 |
623 | If you develop a new program, and you want it to be of the greatest
624 | possible use to the public, the best way to achieve this is to make it
625 | free software which everyone can redistribute and change under these terms.
626 |
627 | To do so, attach the following notices to the program. It is safest
628 | to attach them to the start of each source file to most effectively
629 | state the exclusion of warranty; and each file should have at least
630 | the "copyright" line and a pointer to where the full notice is found.
631 |
632 |
633 | Copyright (C)
634 |
635 | This program is free software: you can redistribute it and/or modify
636 | it under the terms of the GNU Affero General Public License as published
637 | by the Free Software Foundation, either version 3 of the License, or
638 | (at your option) any later version.
639 |
640 | This program is distributed in the hope that it will be useful,
641 | but WITHOUT ANY WARRANTY; without even the implied warranty of
642 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
643 | GNU Affero General Public License for more details.
644 |
645 | You should have received a copy of the GNU Affero General Public License
646 | along with this program. If not, see .
647 |
648 | Also add information on how to contact you by electronic and paper mail.
649 |
650 | If your software can interact with users remotely through a computer
651 | network, you should also make sure that it provides a way for users to
652 | get its source. For example, if your program is a web application, its
653 | interface could display a "Source" link that leads users to an archive
654 | of the code. There are many ways you could offer source, and different
655 | solutions will be better for different programs; see section 13 for the
656 | specific requirements.
657 |
658 | You should also get your employer (if you work as a programmer) or school,
659 | if any, to sign a "copyright disclaimer" for the program, if necessary.
660 | For more information on this, and how to apply and follow the GNU AGPL, see
661 | .
662 |
--------------------------------------------------------------------------------