@preclaim/core 0.2.3 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/docs.d.ts +40 -0
- package/dist/docs.d.ts.map +1 -0
- package/dist/docs.js +191 -0
- package/dist/docs.js.map +1 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/src/docs.ts +240 -0
- package/src/index.ts +2 -0
package/dist/docs.d.ts
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
export interface DocCommandOption {
|
|
2
|
+
flags: string;
|
|
3
|
+
description: string;
|
|
4
|
+
default?: string;
|
|
5
|
+
}
|
|
6
|
+
export interface DocCommand {
|
|
7
|
+
name: string;
|
|
8
|
+
usage: string;
|
|
9
|
+
description: string;
|
|
10
|
+
options?: DocCommandOption[];
|
|
11
|
+
example?: string;
|
|
12
|
+
}
|
|
13
|
+
export interface DocToolArg {
|
|
14
|
+
name: string;
|
|
15
|
+
type: string;
|
|
16
|
+
required: boolean;
|
|
17
|
+
description: string;
|
|
18
|
+
}
|
|
19
|
+
export interface DocTool {
|
|
20
|
+
name: string;
|
|
21
|
+
description: string;
|
|
22
|
+
args: DocToolArg[];
|
|
23
|
+
}
|
|
24
|
+
export interface DocHook {
|
|
25
|
+
name: string;
|
|
26
|
+
event: string;
|
|
27
|
+
description: string;
|
|
28
|
+
}
|
|
29
|
+
export interface DocConfigEntry {
|
|
30
|
+
key: string;
|
|
31
|
+
description: string;
|
|
32
|
+
default?: string;
|
|
33
|
+
}
|
|
34
|
+
export declare const cliCommands: DocCommand[];
|
|
35
|
+
export declare const mcpTools: DocTool[];
|
|
36
|
+
export declare const hooks: DocHook[];
|
|
37
|
+
export declare const configEntries: DocConfigEntry[];
|
|
38
|
+
export declare function getCommandDescription(name: string): string;
|
|
39
|
+
export declare function getToolDescription(name: string): string;
|
|
40
|
+
//# sourceMappingURL=docs.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,UAAU,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,eAAO,MAAM,WAAW,EAAE,UAAU,EAmFnC,CAAC;AAIF,eAAO,MAAM,QAAQ,EAAE,OAAO,EAmC7B,CAAC;AAIF,eAAO,MAAM,KAAK,EAAE,OAAO,EAqB1B,CAAC;AAIF,eAAO,MAAM,aAAa,EAAE,cAAc,EA6BzC,CAAC;AAIF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI1D;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIvD"}
|
package/dist/docs.js
ADDED
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
// ─── Docs: single source of truth for CLI, MCP, and web docs ───
|
|
2
|
+
// ─── CLI Commands ───
|
|
3
|
+
export const cliCommands = [
|
|
4
|
+
{
|
|
5
|
+
name: 'init',
|
|
6
|
+
usage: 'preclaim init',
|
|
7
|
+
description: 'Initialize Preclaim in the current project',
|
|
8
|
+
options: [
|
|
9
|
+
{ flags: '--backend <url>', description: 'Backend URL', default: 'https://preclaim.dev' },
|
|
10
|
+
{ flags: '--project-id <id>', description: 'Project ID' },
|
|
11
|
+
],
|
|
12
|
+
example: 'preclaim init --project-id my-project',
|
|
13
|
+
},
|
|
14
|
+
{
|
|
15
|
+
name: 'login',
|
|
16
|
+
usage: 'preclaim login',
|
|
17
|
+
description: 'Authenticate with Preclaim',
|
|
18
|
+
example: 'preclaim login',
|
|
19
|
+
},
|
|
20
|
+
{
|
|
21
|
+
name: 'lock',
|
|
22
|
+
usage: 'preclaim lock <file>',
|
|
23
|
+
description: 'Lock a file',
|
|
24
|
+
options: [
|
|
25
|
+
{ flags: '-s, --session <id>', description: 'Session ID' },
|
|
26
|
+
{ flags: '-t, --ttl <minutes>', description: 'Lock TTL in minutes' },
|
|
27
|
+
],
|
|
28
|
+
example: 'preclaim lock src/api/auth.ts --ttl 30',
|
|
29
|
+
},
|
|
30
|
+
{
|
|
31
|
+
name: 'unlock',
|
|
32
|
+
usage: 'preclaim unlock [file]',
|
|
33
|
+
description: 'Release a file lock',
|
|
34
|
+
options: [
|
|
35
|
+
{ flags: '-s, --session <id>', description: 'Session ID' },
|
|
36
|
+
{ flags: '-a, --all', description: 'Release all locks for this session' },
|
|
37
|
+
],
|
|
38
|
+
example: 'preclaim unlock src/api/auth.ts',
|
|
39
|
+
},
|
|
40
|
+
{
|
|
41
|
+
name: 'status',
|
|
42
|
+
usage: 'preclaim status',
|
|
43
|
+
description: 'Show active locks for this project',
|
|
44
|
+
example: 'preclaim status',
|
|
45
|
+
},
|
|
46
|
+
{
|
|
47
|
+
name: 'check',
|
|
48
|
+
usage: 'preclaim check <files...>',
|
|
49
|
+
description: 'Check lock status for files',
|
|
50
|
+
example: 'preclaim check src/api/auth.ts src/lib/db.ts',
|
|
51
|
+
},
|
|
52
|
+
{
|
|
53
|
+
name: 'whoami',
|
|
54
|
+
usage: 'preclaim whoami',
|
|
55
|
+
description: 'Show current user info',
|
|
56
|
+
example: 'preclaim whoami',
|
|
57
|
+
},
|
|
58
|
+
{
|
|
59
|
+
name: 'config',
|
|
60
|
+
usage: 'preclaim config',
|
|
61
|
+
description: 'View or modify project configuration',
|
|
62
|
+
options: [
|
|
63
|
+
{ flags: '--get <key>', description: 'Get a config value' },
|
|
64
|
+
{ flags: '--set <key=value>', description: 'Set a config value' },
|
|
65
|
+
],
|
|
66
|
+
example: 'preclaim config --set ttl=30',
|
|
67
|
+
},
|
|
68
|
+
{
|
|
69
|
+
name: 'sessions',
|
|
70
|
+
usage: 'preclaim sessions',
|
|
71
|
+
description: 'Show active sessions for this project',
|
|
72
|
+
example: 'preclaim sessions',
|
|
73
|
+
},
|
|
74
|
+
{
|
|
75
|
+
name: 'logs',
|
|
76
|
+
usage: 'preclaim logs',
|
|
77
|
+
description: 'Show recent lock activity for this project',
|
|
78
|
+
example: 'preclaim logs',
|
|
79
|
+
},
|
|
80
|
+
{
|
|
81
|
+
name: 'install-hooks',
|
|
82
|
+
usage: 'preclaim install-hooks',
|
|
83
|
+
description: 'Install Claude Code hooks in the current project',
|
|
84
|
+
example: 'preclaim install-hooks',
|
|
85
|
+
},
|
|
86
|
+
];
|
|
87
|
+
// ─── MCP Tools ───
|
|
88
|
+
export const mcpTools = [
|
|
89
|
+
{
|
|
90
|
+
name: 'preclaim_lock',
|
|
91
|
+
description: 'Lock a file before editing it. Call this BEFORE writing to any file to prevent conflicts with other AI sessions. Returns whether the lock was acquired or if another session holds it.',
|
|
92
|
+
args: [
|
|
93
|
+
{ name: 'file_path', type: 'string', required: true, description: 'Path to the file to lock (relative or absolute)' },
|
|
94
|
+
{ name: 'ttl_minutes', type: 'number', required: false, description: 'Lock duration in minutes (default: from project config)' },
|
|
95
|
+
],
|
|
96
|
+
},
|
|
97
|
+
{
|
|
98
|
+
name: 'preclaim_unlock',
|
|
99
|
+
description: 'Release a lock on a file, or all locks for this session. Call this after committing changes.',
|
|
100
|
+
args: [
|
|
101
|
+
{ name: 'file_path', type: 'string', required: false, description: 'Specific file to unlock. Omit to release all locks.' },
|
|
102
|
+
],
|
|
103
|
+
},
|
|
104
|
+
{
|
|
105
|
+
name: 'preclaim_check',
|
|
106
|
+
description: 'Check lock status of one or more files without acquiring locks. Use this to see if files are available before editing.',
|
|
107
|
+
args: [
|
|
108
|
+
{ name: 'file_paths', type: 'string[]', required: true, description: 'Files to check (1-100 paths)' },
|
|
109
|
+
],
|
|
110
|
+
},
|
|
111
|
+
{
|
|
112
|
+
name: 'preclaim_status',
|
|
113
|
+
description: 'List all active locks and sessions for this project. Shows who is working on what.',
|
|
114
|
+
args: [],
|
|
115
|
+
},
|
|
116
|
+
{
|
|
117
|
+
name: 'preclaim_read',
|
|
118
|
+
description: 'Signal that you are reading a file. This lets other sessions know you are looking at this file (soft signal, 60s TTL). Call this when reading files to improve coordination.',
|
|
119
|
+
args: [
|
|
120
|
+
{ name: 'file_path', type: 'string', required: true, description: 'Path to the file being read' },
|
|
121
|
+
],
|
|
122
|
+
},
|
|
123
|
+
];
|
|
124
|
+
// ─── Hooks ───
|
|
125
|
+
export const hooks = [
|
|
126
|
+
{
|
|
127
|
+
name: 'PreToolUse',
|
|
128
|
+
event: 'Before every tool call',
|
|
129
|
+
description: 'The gatekeeper. Intercepts Edit/Write/MultiEdit to acquire file locks before changes, and Read to register soft signals. Allows the tool to proceed if the lock is acquired, blocks with a warning if another session holds the lock.',
|
|
130
|
+
},
|
|
131
|
+
{
|
|
132
|
+
name: 'PostToolUse',
|
|
133
|
+
event: 'After every tool call',
|
|
134
|
+
description: 'Commit detector. Watches for git commit commands and automatically releases all session locks when a commit is detected.',
|
|
135
|
+
},
|
|
136
|
+
{
|
|
137
|
+
name: 'SessionStart',
|
|
138
|
+
event: 'When a Claude Code session starts',
|
|
139
|
+
description: 'Registers the session with Preclaim, starts the heartbeat daemon for automatic lock expiry, and injects a system message with current lock status.',
|
|
140
|
+
},
|
|
141
|
+
{
|
|
142
|
+
name: 'Stop',
|
|
143
|
+
event: 'When a Claude Code session ends',
|
|
144
|
+
description: 'No-op by design. Cleanup is handled by the activity-aware heartbeat daemon (locks expire when idle), server-side pg_cron cleanup, and daemon self-exit after inactivity.',
|
|
145
|
+
},
|
|
146
|
+
];
|
|
147
|
+
// ─── Configuration ───
|
|
148
|
+
export const configEntries = [
|
|
149
|
+
{
|
|
150
|
+
key: 'backend',
|
|
151
|
+
description: 'URL of the Preclaim backend API',
|
|
152
|
+
default: 'https://preclaim.dev',
|
|
153
|
+
},
|
|
154
|
+
{
|
|
155
|
+
key: 'projectId',
|
|
156
|
+
description: 'Your Preclaim project ID (set during init)',
|
|
157
|
+
},
|
|
158
|
+
{
|
|
159
|
+
key: 'ttl',
|
|
160
|
+
description: 'Default lock TTL in minutes',
|
|
161
|
+
default: '30',
|
|
162
|
+
},
|
|
163
|
+
{
|
|
164
|
+
key: 'failOpen',
|
|
165
|
+
description: 'Allow tool use when Preclaim is unreachable',
|
|
166
|
+
default: 'true',
|
|
167
|
+
},
|
|
168
|
+
{
|
|
169
|
+
key: 'ignore',
|
|
170
|
+
description: 'Glob patterns for files to never lock (e.g. *.md, dist/**)',
|
|
171
|
+
default: '[]',
|
|
172
|
+
},
|
|
173
|
+
{
|
|
174
|
+
key: 'idleTimeoutMinutes',
|
|
175
|
+
description: 'Minutes of inactivity before the heartbeat daemon releases locks',
|
|
176
|
+
},
|
|
177
|
+
];
|
|
178
|
+
// ─── Helpers for consumers (CLI, MCP) ───
|
|
179
|
+
export function getCommandDescription(name) {
|
|
180
|
+
const cmd = cliCommands.find(c => c.name === name);
|
|
181
|
+
if (!cmd)
|
|
182
|
+
throw new Error(`Unknown command: ${name}`);
|
|
183
|
+
return cmd.description;
|
|
184
|
+
}
|
|
185
|
+
export function getToolDescription(name) {
|
|
186
|
+
const tool = mcpTools.find(t => t.name === name);
|
|
187
|
+
if (!tool)
|
|
188
|
+
throw new Error(`Unknown tool: ${name}`);
|
|
189
|
+
return tool.description;
|
|
190
|
+
}
|
|
191
|
+
//# sourceMappingURL=docs.js.map
|
package/dist/docs.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"docs.js","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":"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"}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
1
|
export { PreclaimClient } from './client.js';
|
|
2
|
+
export { cliCommands, mcpTools, hooks, configEntries, getCommandDescription, getToolDescription } from './docs.js';
|
|
3
|
+
export type { DocCommand, DocCommandOption, DocTool, DocToolArg, DocHook, DocConfigEntry } from './docs.js';
|
|
2
4
|
export { findConfig, loadCredentials, getCredentialsPath, defaultConfig, getSupabaseConfig, saveCredentials, refreshCredentials } from './config.js';
|
|
3
5
|
export type { ActivityEntry, Organization, Profile, Project, Session, SessionWithProfile, Lock, LockHolder, LockHistoryEntry, FileInterest, RegisterInterestRequest, CheckInterestsRequest, CheckInterestsResult, ClaimStatus, ClaimResult, ClaimRequest, BatchCheckRequest, BatchCheckResult, HeartbeatRequest, HeartbeatResult, SessionRegisterRequest, ReleaseRequest, ReleaseResult, StatsResult, PreclaimConfig, PreclaimCredentials, ApiResponse, HookInput, HookResult, MeResult, VersionResult, } from './types.js';
|
|
4
6
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,kBAAkB,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACrJ,YAAY,EACV,aAAa,EACb,YAAY,EACZ,OAAO,EACP,OAAO,EACP,OAAO,EACP,kBAAkB,EAClB,IAAI,EACJ,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,WAAW,EACX,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,cAAc,EACd,aAAa,EACb,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,SAAS,EACT,UAAU,EACV,QAAQ,EACR,aAAa,GACd,MAAM,YAAY,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACnH,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC5G,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,kBAAkB,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACrJ,YAAY,EACV,aAAa,EACb,YAAY,EACZ,OAAO,EACP,OAAO,EACP,OAAO,EACP,kBAAkB,EAClB,IAAI,EACJ,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,WAAW,EACX,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,cAAc,EACd,aAAa,EACb,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,SAAS,EACT,UAAU,EACV,QAAQ,EACR,aAAa,GACd,MAAM,YAAY,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
1
|
export { PreclaimClient } from './client.js';
|
|
2
|
+
export { cliCommands, mcpTools, hooks, configEntries, getCommandDescription, getToolDescription } from './docs.js';
|
|
2
3
|
export { findConfig, loadCredentials, getCredentialsPath, defaultConfig, getSupabaseConfig, saveCredentials, refreshCredentials } from './config.js';
|
|
3
4
|
//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,kBAAkB,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAEnH,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,kBAAkB,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}
|
package/package.json
CHANGED
package/src/docs.ts
ADDED
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
// ─── Docs: single source of truth for CLI, MCP, and web docs ───
|
|
2
|
+
|
|
3
|
+
// ─── Types ───
|
|
4
|
+
|
|
5
|
+
export interface DocCommandOption {
|
|
6
|
+
flags: string;
|
|
7
|
+
description: string;
|
|
8
|
+
default?: string;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
export interface DocCommand {
|
|
12
|
+
name: string;
|
|
13
|
+
usage: string;
|
|
14
|
+
description: string;
|
|
15
|
+
options?: DocCommandOption[];
|
|
16
|
+
example?: string;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export interface DocToolArg {
|
|
20
|
+
name: string;
|
|
21
|
+
type: string;
|
|
22
|
+
required: boolean;
|
|
23
|
+
description: string;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export interface DocTool {
|
|
27
|
+
name: string;
|
|
28
|
+
description: string;
|
|
29
|
+
args: DocToolArg[];
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export interface DocHook {
|
|
33
|
+
name: string;
|
|
34
|
+
event: string;
|
|
35
|
+
description: string;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
export interface DocConfigEntry {
|
|
39
|
+
key: string;
|
|
40
|
+
description: string;
|
|
41
|
+
default?: string;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
// ─── CLI Commands ───
|
|
45
|
+
|
|
46
|
+
export const cliCommands: DocCommand[] = [
|
|
47
|
+
{
|
|
48
|
+
name: 'init',
|
|
49
|
+
usage: 'preclaim init',
|
|
50
|
+
description: 'Initialize Preclaim in the current project',
|
|
51
|
+
options: [
|
|
52
|
+
{ flags: '--backend <url>', description: 'Backend URL', default: 'https://preclaim.dev' },
|
|
53
|
+
{ flags: '--project-id <id>', description: 'Project ID' },
|
|
54
|
+
],
|
|
55
|
+
example: 'preclaim init --project-id my-project',
|
|
56
|
+
},
|
|
57
|
+
{
|
|
58
|
+
name: 'login',
|
|
59
|
+
usage: 'preclaim login',
|
|
60
|
+
description: 'Authenticate with Preclaim',
|
|
61
|
+
example: 'preclaim login',
|
|
62
|
+
},
|
|
63
|
+
{
|
|
64
|
+
name: 'lock',
|
|
65
|
+
usage: 'preclaim lock <file>',
|
|
66
|
+
description: 'Lock a file',
|
|
67
|
+
options: [
|
|
68
|
+
{ flags: '-s, --session <id>', description: 'Session ID' },
|
|
69
|
+
{ flags: '-t, --ttl <minutes>', description: 'Lock TTL in minutes' },
|
|
70
|
+
],
|
|
71
|
+
example: 'preclaim lock src/api/auth.ts --ttl 30',
|
|
72
|
+
},
|
|
73
|
+
{
|
|
74
|
+
name: 'unlock',
|
|
75
|
+
usage: 'preclaim unlock [file]',
|
|
76
|
+
description: 'Release a file lock',
|
|
77
|
+
options: [
|
|
78
|
+
{ flags: '-s, --session <id>', description: 'Session ID' },
|
|
79
|
+
{ flags: '-a, --all', description: 'Release all locks for this session' },
|
|
80
|
+
],
|
|
81
|
+
example: 'preclaim unlock src/api/auth.ts',
|
|
82
|
+
},
|
|
83
|
+
{
|
|
84
|
+
name: 'status',
|
|
85
|
+
usage: 'preclaim status',
|
|
86
|
+
description: 'Show active locks for this project',
|
|
87
|
+
example: 'preclaim status',
|
|
88
|
+
},
|
|
89
|
+
{
|
|
90
|
+
name: 'check',
|
|
91
|
+
usage: 'preclaim check <files...>',
|
|
92
|
+
description: 'Check lock status for files',
|
|
93
|
+
example: 'preclaim check src/api/auth.ts src/lib/db.ts',
|
|
94
|
+
},
|
|
95
|
+
{
|
|
96
|
+
name: 'whoami',
|
|
97
|
+
usage: 'preclaim whoami',
|
|
98
|
+
description: 'Show current user info',
|
|
99
|
+
example: 'preclaim whoami',
|
|
100
|
+
},
|
|
101
|
+
{
|
|
102
|
+
name: 'config',
|
|
103
|
+
usage: 'preclaim config',
|
|
104
|
+
description: 'View or modify project configuration',
|
|
105
|
+
options: [
|
|
106
|
+
{ flags: '--get <key>', description: 'Get a config value' },
|
|
107
|
+
{ flags: '--set <key=value>', description: 'Set a config value' },
|
|
108
|
+
],
|
|
109
|
+
example: 'preclaim config --set ttl=30',
|
|
110
|
+
},
|
|
111
|
+
{
|
|
112
|
+
name: 'sessions',
|
|
113
|
+
usage: 'preclaim sessions',
|
|
114
|
+
description: 'Show active sessions for this project',
|
|
115
|
+
example: 'preclaim sessions',
|
|
116
|
+
},
|
|
117
|
+
{
|
|
118
|
+
name: 'logs',
|
|
119
|
+
usage: 'preclaim logs',
|
|
120
|
+
description: 'Show recent lock activity for this project',
|
|
121
|
+
example: 'preclaim logs',
|
|
122
|
+
},
|
|
123
|
+
{
|
|
124
|
+
name: 'install-hooks',
|
|
125
|
+
usage: 'preclaim install-hooks',
|
|
126
|
+
description: 'Install Claude Code hooks in the current project',
|
|
127
|
+
example: 'preclaim install-hooks',
|
|
128
|
+
},
|
|
129
|
+
];
|
|
130
|
+
|
|
131
|
+
// ─── MCP Tools ───
|
|
132
|
+
|
|
133
|
+
export const mcpTools: DocTool[] = [
|
|
134
|
+
{
|
|
135
|
+
name: 'preclaim_lock',
|
|
136
|
+
description: 'Lock a file before editing it. Call this BEFORE writing to any file to prevent conflicts with other AI sessions. Returns whether the lock was acquired or if another session holds it.',
|
|
137
|
+
args: [
|
|
138
|
+
{ name: 'file_path', type: 'string', required: true, description: 'Path to the file to lock (relative or absolute)' },
|
|
139
|
+
{ name: 'ttl_minutes', type: 'number', required: false, description: 'Lock duration in minutes (default: from project config)' },
|
|
140
|
+
],
|
|
141
|
+
},
|
|
142
|
+
{
|
|
143
|
+
name: 'preclaim_unlock',
|
|
144
|
+
description: 'Release a lock on a file, or all locks for this session. Call this after committing changes.',
|
|
145
|
+
args: [
|
|
146
|
+
{ name: 'file_path', type: 'string', required: false, description: 'Specific file to unlock. Omit to release all locks.' },
|
|
147
|
+
],
|
|
148
|
+
},
|
|
149
|
+
{
|
|
150
|
+
name: 'preclaim_check',
|
|
151
|
+
description: 'Check lock status of one or more files without acquiring locks. Use this to see if files are available before editing.',
|
|
152
|
+
args: [
|
|
153
|
+
{ name: 'file_paths', type: 'string[]', required: true, description: 'Files to check (1-100 paths)' },
|
|
154
|
+
],
|
|
155
|
+
},
|
|
156
|
+
{
|
|
157
|
+
name: 'preclaim_status',
|
|
158
|
+
description: 'List all active locks and sessions for this project. Shows who is working on what.',
|
|
159
|
+
args: [],
|
|
160
|
+
},
|
|
161
|
+
{
|
|
162
|
+
name: 'preclaim_read',
|
|
163
|
+
description: 'Signal that you are reading a file. This lets other sessions know you are looking at this file (soft signal, 60s TTL). Call this when reading files to improve coordination.',
|
|
164
|
+
args: [
|
|
165
|
+
{ name: 'file_path', type: 'string', required: true, description: 'Path to the file being read' },
|
|
166
|
+
],
|
|
167
|
+
},
|
|
168
|
+
];
|
|
169
|
+
|
|
170
|
+
// ─── Hooks ───
|
|
171
|
+
|
|
172
|
+
export const hooks: DocHook[] = [
|
|
173
|
+
{
|
|
174
|
+
name: 'PreToolUse',
|
|
175
|
+
event: 'Before every tool call',
|
|
176
|
+
description: 'The gatekeeper. Intercepts Edit/Write/MultiEdit to acquire file locks before changes, and Read to register soft signals. Allows the tool to proceed if the lock is acquired, blocks with a warning if another session holds the lock.',
|
|
177
|
+
},
|
|
178
|
+
{
|
|
179
|
+
name: 'PostToolUse',
|
|
180
|
+
event: 'After every tool call',
|
|
181
|
+
description: 'Commit detector. Watches for git commit commands and automatically releases all session locks when a commit is detected.',
|
|
182
|
+
},
|
|
183
|
+
{
|
|
184
|
+
name: 'SessionStart',
|
|
185
|
+
event: 'When a Claude Code session starts',
|
|
186
|
+
description: 'Registers the session with Preclaim, starts the heartbeat daemon for automatic lock expiry, and injects a system message with current lock status.',
|
|
187
|
+
},
|
|
188
|
+
{
|
|
189
|
+
name: 'Stop',
|
|
190
|
+
event: 'When a Claude Code session ends',
|
|
191
|
+
description: 'No-op by design. Cleanup is handled by the activity-aware heartbeat daemon (locks expire when idle), server-side pg_cron cleanup, and daemon self-exit after inactivity.',
|
|
192
|
+
},
|
|
193
|
+
];
|
|
194
|
+
|
|
195
|
+
// ─── Configuration ───
|
|
196
|
+
|
|
197
|
+
export const configEntries: DocConfigEntry[] = [
|
|
198
|
+
{
|
|
199
|
+
key: 'backend',
|
|
200
|
+
description: 'URL of the Preclaim backend API',
|
|
201
|
+
default: 'https://preclaim.dev',
|
|
202
|
+
},
|
|
203
|
+
{
|
|
204
|
+
key: 'projectId',
|
|
205
|
+
description: 'Your Preclaim project ID (set during init)',
|
|
206
|
+
},
|
|
207
|
+
{
|
|
208
|
+
key: 'ttl',
|
|
209
|
+
description: 'Default lock TTL in minutes',
|
|
210
|
+
default: '30',
|
|
211
|
+
},
|
|
212
|
+
{
|
|
213
|
+
key: 'failOpen',
|
|
214
|
+
description: 'Allow tool use when Preclaim is unreachable',
|
|
215
|
+
default: 'true',
|
|
216
|
+
},
|
|
217
|
+
{
|
|
218
|
+
key: 'ignore',
|
|
219
|
+
description: 'Glob patterns for files to never lock (e.g. *.md, dist/**)',
|
|
220
|
+
default: '[]',
|
|
221
|
+
},
|
|
222
|
+
{
|
|
223
|
+
key: 'idleTimeoutMinutes',
|
|
224
|
+
description: 'Minutes of inactivity before the heartbeat daemon releases locks',
|
|
225
|
+
},
|
|
226
|
+
];
|
|
227
|
+
|
|
228
|
+
// ─── Helpers for consumers (CLI, MCP) ───
|
|
229
|
+
|
|
230
|
+
export function getCommandDescription(name: string): string {
|
|
231
|
+
const cmd = cliCommands.find(c => c.name === name);
|
|
232
|
+
if (!cmd) throw new Error(`Unknown command: ${name}`);
|
|
233
|
+
return cmd.description;
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
export function getToolDescription(name: string): string {
|
|
237
|
+
const tool = mcpTools.find(t => t.name === name);
|
|
238
|
+
if (!tool) throw new Error(`Unknown tool: ${name}`);
|
|
239
|
+
return tool.description;
|
|
240
|
+
}
|
package/src/index.ts
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
1
|
export { PreclaimClient } from './client.js';
|
|
2
|
+
export { cliCommands, mcpTools, hooks, configEntries, getCommandDescription, getToolDescription } from './docs.js';
|
|
3
|
+
export type { DocCommand, DocCommandOption, DocTool, DocToolArg, DocHook, DocConfigEntry } from './docs.js';
|
|
2
4
|
export { findConfig, loadCredentials, getCredentialsPath, defaultConfig, getSupabaseConfig, saveCredentials, refreshCredentials } from './config.js';
|
|
3
5
|
export type {
|
|
4
6
|
ActivityEntry,
|