preclaim 0.1.0

package/src/commands/init.ts

@@ -0,0 +1,109 @@
+import { writeFile, readFile } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import { defaultConfig, loadCredentials, PreclaimClient } from '@preclaim/core';
+import { loginCommand } from './login.js';
+
+const DEFAULT_BACKEND = 'https://preclaim.dev';
+
+export async function initCommand(opts: { backend?: string; projectId?: string }) {
+  const configPath = join(process.cwd(), '.preclaim.json');
+
+  // Check if already exists
+  try {
+    await readFile(configPath, 'utf-8');
+    console.log('.preclaim.json already exists. Use `preclaim config` to modify.');
+    return;
+  } catch {
+    // File doesn't exist, proceed
+  }
+
+  const backend = opts.backend ?? DEFAULT_BACKEND;
+
+  // If project ID provided directly, skip onboarding
+  if (opts.projectId) {
+    const config = defaultConfig(opts.projectId, backend);
+    await writeFile(configPath, JSON.stringify(config, null, 2) + '\n');
+    console.log(`Created .preclaim.json (project: ${opts.projectId})`);
+    printNextSteps();
+    return;
+  }
+
+  // Check if logged in, if not: login first
+  let creds = await loadCredentials();
+  if (!creds) {
+    console.log('Not logged in. Starting authentication...\n');
+    await loginCommand();
+    creds = await loadCredentials();
+    if (!creds) {
+      console.error('Login failed. Please try again.');
+      process.exit(1);
+    }
+    console.log('');
+  }
+
+  // Derive project name from directory
+  const dirName = basename(process.cwd());
+  const projectSlug = dirName.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-');
+  const projectName = dirName;
+
+  console.log(`Setting up Preclaim for "${projectName}"...`);
+
+  // Call onboard API
+  const client = new PreclaimClient({
+    baseUrl: backend,
+    accessToken: creds.accessToken,
+    timeoutMs: 10000,
+  });
+
+  const res = await fetch(`${backend}/api/v1/onboard`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${creds.accessToken}`,
+    },
+    body: JSON.stringify({
+      project_name: projectName,
+      project_slug: projectSlug,
+    }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text();
+    console.error(`Failed to create project: ${body}`);
+    process.exit(1);
+  }
+
+  const { data } = await res.json() as { data: { project_id: string; org_id: string; already_existed: boolean } };
+
+  if (data.already_existed) {
+    console.log(`Project "${projectName}" already exists, using existing project.`);
+  } else {
+    console.log(`Project "${projectName}" created.`);
+  }
+
+  // Update credentials with org_id
+  if (creds.user.orgId !== data.org_id) {
+    creds.user.orgId = data.org_id;
+    const { getCredentialsPath } = await import('@preclaim/core');
+    const { writeFile: wf, mkdir } = await import('node:fs/promises');
+    const { dirname } = await import('node:path');
+    const credPath = getCredentialsPath();
+    await mkdir(dirname(credPath), { recursive: true });
+    await wf(credPath, JSON.stringify(creds, null, 2) + '\n', { mode: 0o600 });
+  }
+
+  // Write config
+  const config = defaultConfig(data.project_id, backend);
+  await writeFile(configPath, JSON.stringify(config, null, 2) + '\n');
+
+  console.log(`\nCreated .preclaim.json`);
+  printNextSteps();
+}
+
+function printNextSteps() {
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. preclaim install-hooks');
+  console.log('  2. Commit .preclaim.json to your repo');
+  console.log('  3. Open multiple Claude Code terminals — locks are automatic');
+}

package/src/commands/install-hooks.ts

@@ -0,0 +1,72 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+interface ClaudeSettings {
+  hooks?: Record<string, Array<{
+    matcher: string;
+    hooks: Array<{
+      type: string;
+      command: string;
+    }>;
+  }>>;
+}
+
+export async function installHooksCommand() {
+  const hooksDir = join(__dirname, '..', 'hooks');
+  const settingsDir = join(process.cwd(), '.claude');
+  const settingsPath = join(settingsDir, 'settings.json');
+
+  // Read existing settings or create new
+  let settings: ClaudeSettings = {};
+  try {
+    const raw = await readFile(settingsPath, 'utf-8');
+    settings = JSON.parse(raw);
+  } catch {
+    // File doesn't exist
+  }
+
+  settings.hooks = {
+    PreToolUse: [{
+      matcher: '',
+      hooks: [{
+        type: 'command',
+        command: `node ${join(hooksDir, 'pre-tool-use.js')}`,
+      }],
+    }],
+    PostToolUse: [{
+      matcher: '',
+      hooks: [{
+        type: 'command',
+        command: `node ${join(hooksDir, 'post-tool-use.js')}`,
+      }],
+    }],
+    Stop: [{
+      matcher: '',
+      hooks: [{
+        type: 'command',
+        command: `node ${join(hooksDir, 'stop.js')}`,
+      }],
+    }],
+    SessionStart: [{
+      matcher: '',
+      hooks: [{
+        type: 'command',
+        command: `node ${join(hooksDir, 'session-start.js')}`,
+      }],
+    }],
+  };
+
+  await mkdir(settingsDir, { recursive: true });
+  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+
+  console.log('Claude Code hooks installed in .claude/settings.json');
+  console.log('');
+  console.log('Hooks configured:');
+  console.log('  - PreToolUse: file lock gatekeeper');
+  console.log('  - PostToolUse: commit detection → release locks');
+  console.log('  - Stop: session cleanup');
+  console.log('  - SessionStart: session registration + heartbeat');
+}

package/src/commands/lock.ts

@@ -0,0 +1,30 @@
+import { resolveContext } from '../lib/client-factory.js';
+
+export async function lockCommand(filePath: string, opts: { session?: string; ttl?: string }) {
+  const { client, config, credentials } = await resolveContext();
+  const sessionId = opts.session ?? `manual_${crypto.randomUUID().slice(0, 8)}`;
+  const ttl = opts.ttl ? parseInt(opts.ttl, 10) : config.ttl;
+
+  const result = await client.claimFile({
+    project_id: config.projectId,
+    file_path: filePath,
+    session_id: sessionId,
+    ttl_minutes: ttl,
+  });
+
+  if (result.error) {
+    console.error(`Failed to lock: ${result.error}`);
+    process.exit(1);
+  }
+
+  const data = result.data!;
+
+  if (data.status === 'acquired' || data.status === 'already_held') {
+    console.log(`Locked: ${filePath} (expires: ${new Date(data.expires_at!).toLocaleTimeString()})`);
+  } else if (data.status === 'conflict') {
+    console.error(`Conflict: ${filePath} is locked by session ${data.holder!.session_id.slice(0, 8)}…`);
+    console.error(`  Acquired: ${new Date(data.holder!.acquired_at).toLocaleTimeString()}`);
+    console.error(`  Expires:  ${new Date(data.holder!.expires_at).toLocaleTimeString()}`);
+    process.exit(1);
+  }
+}

package/src/commands/login.ts

@@ -0,0 +1,120 @@
+import { createServer, type Server } from 'node:http';
+import { writeFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { getCredentialsPath, findConfig } from '@preclaim/core';
+
+const SUPABASE_URL = 'https://aawbukcvngdffueowjsa.supabase.co';
+const SUPABASE_ANON_KEY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImFhd2J1a2N2bmdkZmZ1ZW93anNhIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzM3NjI2NTcsImV4cCI6MjA4OTMzODY1N30.pwAyjgnbdoZmmJdsG2jF0nbvT4hueb8UZvstsdYhFFs';
+
+export async function loginCommand() {
+  const server = createServer();
+
+  const port = await new Promise<number>((resolve) => {
+    server.listen(0, () => {
+      resolve((server.address() as { port: number }).port);
+    });
+  });
+
+  const redirectTo = `http://localhost:${port}/callback`;
+  const oauthUrl = `${SUPABASE_URL}/auth/v1/authorize?provider=github&redirect_to=${encodeURIComponent(redirectTo)}`;
+
+  console.log('Opening browser for GitHub authentication...');
+  console.log(`If browser doesn't open, visit:\n${oauthUrl}\n`);
+
+  const { exec } = await import('node:child_process');
+  const openCmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+  exec(`${openCmd} "${oauthUrl}"`);
+
+  await handleAuthCallback(server);
+}
+
+function handleAuthCallback(server: Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.on('request', async (req, res) => {
+      const url = new URL(req.url!, `http://localhost`);
+
+      if (url.pathname === '/callback') {
+        // Supabase implicit flow: tokens come in hash fragment.
+        // Serve a page that extracts them and POSTs to /token.
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end(`<!DOCTYPE html><html><body>
+<h1>Logging in to Preclaim...</h1>
+<script>
+const hash = window.location.hash.substring(1);
+const params = new URLSearchParams(hash);
+const access_token = params.get('access_token');
+const refresh_token = params.get('refresh_token');
+const expires_in = params.get('expires_in');
+if (access_token) {
+  fetch('/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ access_token, refresh_token, expires_in })
+  }).then(() => {
+    document.body.innerHTML = '<h1>Logged in to Preclaim!</h1><p>You can close this tab.</p>';
+  });
+} else {
+  document.body.innerHTML = '<h1>Login failed</h1><p>No token received. Check the URL.</p>';
+}
+</script></body></html>`);
+        return;
+      }
+
+      if (url.pathname === '/token' && req.method === 'POST') {
+        let body = '';
+        req.on('data', (chunk: Buffer) => { body += chunk; });
+        req.on('end', async () => {
+          try {
+            const { access_token, refresh_token, expires_in } = JSON.parse(body);
+
+            // Get user info
+            const userRes = await fetch(`${SUPABASE_URL}/auth/v1/user`, {
+              headers: {
+                'Authorization': `Bearer ${access_token}`,
+                'apikey': SUPABASE_ANON_KEY,
+              },
+            });
+
+            if (!userRes.ok) throw new Error(`Failed to get user info: ${userRes.status}`);
+
+            const user = await userRes.json() as { id: string; email?: string };
+
+            // Save credentials
+            const credPath = getCredentialsPath();
+            await mkdir(dirname(credPath), { recursive: true });
+            await writeFile(credPath, JSON.stringify({
+              accessToken: access_token,
+              refreshToken: refresh_token,
+              expiresAt: new Date(Date.now() + parseInt(expires_in) * 1000).toISOString(),
+              user: {
+                id: user.id,
+                email: user.email ?? '',
+                orgId: '',
+              },
+            }, null, 2) + '\n', { mode: 0o600 });
+
+            res.writeHead(200);
+            res.end('ok');
+
+            console.log(`Logged in as ${user.email ?? user.id}`);
+            server.close();
+            resolve();
+          } catch (err) {
+            res.writeHead(500);
+            res.end('error');
+            console.error('Login failed:', err);
+            server.close();
+            reject(err);
+          }
+        });
+        return;
+      }
+    });
+
+    setTimeout(() => {
+      console.error('Login timed out.');
+      server.close();
+      process.exit(1);
+    }, 120_000);
+  });
+}

package/src/commands/status.ts

@@ -0,0 +1,15 @@
+import { resolveContext } from '../lib/client-factory.js';
+import { formatLockTable } from '../lib/output.js';
+
+export async function statusCommand() {
+  const { client, config } = await resolveContext();
+
+  const result = await client.listLocks(config.projectId);
+
+  if (result.error) {
+    console.error(`Failed to fetch status: ${result.error}`);
+    process.exit(1);
+  }
+
+  console.log(formatLockTable(result.data!));
+}

package/src/commands/unlock.ts

@@ -0,0 +1,25 @@
+import { resolveContext } from '../lib/client-factory.js';
+
+export async function unlockCommand(filePath: string | undefined, opts: { session?: string; all?: boolean }) {
+  const { client, config } = await resolveContext();
+
+  if (!filePath && !opts.all) {
+    console.error('Specify a file path or use --all to release all locks.');
+    process.exit(1);
+  }
+
+  const sessionId = opts.session ?? `manual_${crypto.randomUUID().slice(0, 8)}`;
+
+  const result = await client.releaseLocks({
+    project_id: config.projectId,
+    file_path: filePath,
+    session_id: sessionId,
+  });
+
+  if (result.error) {
+    console.error(`Failed to unlock: ${result.error}`);
+    process.exit(1);
+  }
+
+  console.log(`Released ${result.data!.released} lock(s).`);
+}

package/src/commands/whoami.ts

@@ -0,0 +1,15 @@
+import { loadCredentials } from '@preclaim/core';
+
+export async function whoamiCommand() {
+  const creds = await loadCredentials();
+
+  if (!creds) {
+    console.log('Not logged in. Run `preclaim login` to authenticate.');
+    return;
+  }
+
+  console.log(`Email:  ${creds.user.email}`);
+  console.log(`User:   ${creds.user.id}`);
+  console.log(`Org:    ${creds.user.orgId ?? 'none'}`);
+  console.log(`Expires: ${new Date(creds.expiresAt).toLocaleString()}`);
+}

package/src/hooks/heartbeat-daemon.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// Heartbeat daemon — runs as detached background process
+// Extends TTL on all session locks every 60s
+
+import { PreclaimClient } from '@preclaim/core';
+
+const sessionId = process.env.PRECLAIM_SESSION_ID;
+const backend = process.env.PRECLAIM_BACKEND;
+const accessToken = process.env.PRECLAIM_ACCESS_TOKEN;
+
+if (!sessionId || !backend || !accessToken) {
+  process.exit(1);
+}
+
+const client = new PreclaimClient({
+  baseUrl: backend,
+  accessToken,
+  timeoutMs: 5000,
+});
+
+const INTERVAL_MS = 60_000;
+const MAX_FAILURES = 5;
+let failures = 0;
+
+async function heartbeat() {
+  const result = await client.heartbeat({ session_id: sessionId! });
+
+  if (result.error) {
+    failures++;
+    if (failures >= MAX_FAILURES) {
+      process.exit(1);
+    }
+  } else {
+    failures = 0;
+  }
+}
+
+// Run immediately, then every 60s
+heartbeat();
+const interval = setInterval(heartbeat, INTERVAL_MS);
+
+// Cleanup on signals
+function shutdown() {
+  clearInterval(interval);
+  process.exit(0);
+}
+
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);

package/src/hooks/post-tool-use.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// PostToolUse hook — commit detection
+// Detects git commit commands and releases all session locks
+
+import { PreclaimClient, findConfig, loadCredentials } from '@preclaim/core';
+import { readHookInput } from '../lib/hook-io.js';
+
+async function main() {
+  try {
+    const input = await readHookInput();
+
+    // Only match Bash tool calls
+    if (input.tool_name !== 'Bash') return;
+
+    const command = input.tool_input?.command as string | undefined;
+    if (!command) return;
+
+    // Detect git commit (not amend, not just `git commit --help`)
+    const isCommit = /\bgit\s+commit\b/.test(command) && !/--help/.test(command);
+    if (!isCommit) return;
+
+    const found = await findConfig();
+    if (!found) return;
+
+    const creds = await loadCredentials();
+    if (!creds) return;
+
+    const client = new PreclaimClient({
+      baseUrl: found.config.backend,
+      accessToken: creds.accessToken,
+      timeoutMs: 3000,
+    });
+
+    // Release all locks for this session
+    await client.releaseLocks({
+      project_id: found.config.projectId,
+      session_id: input.session_id,
+    });
+  } catch {
+    // Silent fail — non-critical
+  }
+}
+
+main();

package/src/hooks/pre-tool-use.ts

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// PreToolUse hook — the gatekeeper
+// Intercepts Edit/Write/MultiEdit tool calls, claims file locks
+
+import { PreclaimClient, findConfig, loadCredentials } from '@preclaim/core';
+import { readHookInput, writeHookOutput } from '../lib/hook-io.js';
+import { minimatch } from 'minimatch';
+
+const WRITE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit']);
+
+async function main() {
+  try {
+    const input = await readHookInput();
+
+    // Only intercept file-writing tools
+    if (!input.tool_name || !WRITE_TOOLS.has(input.tool_name)) {
+      return; // No output = allow
+    }
+
+    // Extract file path from tool input
+    const filePath = input.tool_input?.file_path as string | undefined;
+    if (!filePath) {
+      return; // No file path = allow
+    }
+
+    // Load config
+    const found = await findConfig();
+    if (!found) {
+      return; // No config = allow (not a preclaim project)
+    }
+
+    // Check ignore patterns
+    const relativePath = filePath.startsWith('/') ? filePath : filePath;
+    if (found.config.ignore.some(pattern => minimatch(relativePath, pattern))) {
+      return; // Ignored file = allow
+    }
+
+    // Load credentials
+    const creds = await loadCredentials();
+    if (!creds) {
+      if (found.config.failOpen) return;
+      writeHookOutput({
+        permissionDecision: 'deny',
+        reason: 'Preclaim: not authenticated. Run `preclaim login`.',
+      });
+      return;
+    }
+
+    // Claim file
+    const client = new PreclaimClient({
+      baseUrl: found.config.backend,
+      accessToken: creds.accessToken,
+      timeoutMs: 2000, // Must be fast
+    });
+
+    const result = await client.claimFile({
+      project_id: found.config.projectId,
+      file_path: relativePath,
+      session_id: input.session_id,
+      ttl_minutes: found.config.ttl,
+    });
+
+    // Network error — fail open
+    if (result.error) {
+      if (found.config.failOpen) {
+        writeHookOutput({
+          permissionDecision: 'allow',
+          systemMessage: `[Preclaim] Warning: could not reach server (${result.error}). Proceeding without lock.`,
+        });
+        return;
+      }
+      writeHookOutput({
+        permissionDecision: 'deny',
+        reason: `Preclaim: server error — ${result.error}`,
+      });
+      return;
+    }
+
+    const data = result.data!;
+
+    if (data.status === 'acquired') {
+      writeHookOutput({
+        permissionDecision: 'allow',
+        systemMessage: `[Preclaim] Locked: ${relativePath} (expires: ${data.expires_at})`,
+      });
+    } else if (data.status === 'already_held') {
+      writeHookOutput({
+        permissionDecision: 'allow',
+        systemMessage: `[Preclaim] Lock extended: ${relativePath} (expires: ${data.expires_at})`,
+      });
+    } else if (data.status === 'conflict') {
+      writeHookOutput({
+        permissionDecision: 'deny',
+        reason: [
+          `Preclaim: ${relativePath} is locked by another session.`,
+          `  Session: ${data.holder!.session_id.slice(0, 8)}…`,
+          `  Since: ${new Date(data.holder!.acquired_at).toLocaleTimeString()}`,
+          `  Expires: ${new Date(data.holder!.expires_at).toLocaleTimeString()}`,
+          '',
+          'Wait for the lock to expire or work on a different file.',
+        ].join('\n'),
+      });
+    }
+  } catch {
+    // Fail open — never block development
+    return;
+  }
+}
+
+main();

package/src/hooks/session-start.ts

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// SessionStart hook — init
+// Registers session, starts heartbeat daemon, injects system message
+
+import { spawn } from 'node:child_process';
+import { writeFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PreclaimClient, findConfig, loadCredentials } from '@preclaim/core';
+import { readHookInput, writeHookOutput } from '../lib/hook-io.js';
+
+async function main() {
+  try {
+    const input = await readHookInput();
+
+    const found = await findConfig();
+    if (!found) return;
+
+    const creds = await loadCredentials();
+    if (!creds) {
+      writeHookOutput({
+        systemMessage: '[Preclaim] Not authenticated. File locking disabled. Run `preclaim login` to enable.',
+      });
+      return;
+    }
+
+    const client = new PreclaimClient({
+      baseUrl: found.config.backend,
+      accessToken: creds.accessToken,
+      timeoutMs: 3000,
+    });
+
+    // Register session
+    const result = await client.registerSession({
+      session_id: input.session_id,
+      project_id: found.config.projectId,
+      provider: 'claude-code',
+    });
+
+    if (result.error) {
+      if (found.config.failOpen) {
+        writeHookOutput({
+          systemMessage: `[Preclaim] Warning: could not register session (${result.error}). File locking may not work.`,
+        });
+        return;
+      }
+    }
+
+    // Start heartbeat daemon
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const heartbeatScript = join(__dirname, 'heartbeat-daemon.js');
+
+    const daemon = spawn('node', [heartbeatScript], {
+      detached: true,
+      stdio: 'ignore',
+      env: {
+        ...process.env,
+        PRECLAIM_SESSION_ID: input.session_id,
+        PRECLAIM_BACKEND: found.config.backend,
+        PRECLAIM_ACCESS_TOKEN: creds.accessToken,
+      },
+    });
+
+    daemon.unref();
+
+    // Save PID for cleanup
+    if (daemon.pid) {
+      await writeFile(join(process.cwd(), '.preclaim.pid'), String(daemon.pid));
+    }
+
+    writeHookOutput({
+      systemMessage: [
+        '[Preclaim] Session registered. File locking is active.',
+        '',
+        'Preclaim coordinates file access across multiple AI sessions:',
+        '- Files are automatically locked when you edit them',
+        '- Locks prevent other sessions from editing the same files',
+        '- Locks are released when you commit or this session ends',
+        '- If a lock is denied, work on a different file',
+      ].join('\n'),
+    });
+  } catch {
+    // Fail open
+  }
+}
+
+main();