devworkspace 0.1.1 → 0.2.1

package/dist/utils/lock.js.map

@@ -1 +1 @@
-{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/utils/lock.ts"],"names":[],"mappings":"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","sourcesContent":["import { promises as fs, unlinkSync } from 'node:fs';\nimport path from 'node:path';\nimport { DevWorkspaceError } from '../errors/index.js';\nimport { ensureDir } from './fs.js';\nimport { onCleanup } from './cleanup.js';\n\nexport interface LockOptions {\n  timeoutMs?: number;\n  staleMs?: number;\n}\n\nfunction pidAlive(pid: number): boolean {\n  try {\n    process.kill(pid, 0);\n    return true;\n  } catch (e) {\n    return (e as NodeJS.ErrnoException).code === 'EPERM';\n  }\n}\n\n/** Exclusive advisory lock stored under .devworkspace/local/. Stale locks (dead pid or too old) are broken. */\nexport async function withLock<T>(workspaceDir: string, fn: () => Promise<T>, opts: LockOptions = {}): Promise<T> {\n  const timeoutMs = opts.timeoutMs ?? 5000;\n  const staleMs = opts.staleMs ?? 60_000;\n  const dir = path.join(workspaceDir, 'local');\n  const lockPath = path.join(dir, 'workspace.lock');\n  await ensureDir(dir);\n  const started = Date.now();\n  for (;;) {\n    try {\n      const fh = await fs.open(lockPath, 'wx');\n      await fh.writeFile(JSON.stringify({ pid: process.pid, at: Date.now() }));\n      await fh.close();\n      break;\n    } catch (e) {\n      if ((e as NodeJS.ErrnoException).code !== 'EEXIST') {\n        throw new DevWorkspaceError('IO', 'Could not acquire the workspace lock.', { cause: e });\n      }\n      let stale: boolean;\n      try {\n        const info = JSON.parse(await fs.readFile(lockPath, 'utf8')) as { pid?: number; at?: number };\n        const age = Date.now() - (info.at ?? 0);\n        stale = age > staleMs || (typeof info.pid === 'number' && !pidAlive(info.pid));\n      } catch {\n        // Unreadable lock: another process may be mid-write, so only break it once it is old.\n        try {\n          stale = Date.now() - (await fs.stat(lockPath)).mtimeMs > 2000;\n        } catch {\n          stale = true;\n        }\n      }\n      if (stale) {\n        await fs.rm(lockPath, { force: true });\n        continue;\n      }\n      if (Date.now() - started > timeoutMs) {\n        throw new DevWorkspaceError('LOCKED', 'Another DevWorkspace process is modifying this workspace.', {\n          hint: `Wait for it to finish, or delete ${path.join('.devworkspace', 'local', 'workspace.lock')} if no process is running.`,\n        });\n      }\n      await new Promise((r) => setTimeout(r, 50));\n    }\n  }\n  const dispose = onCleanup(() => {\n    try {\n      unlinkSync(lockPath);\n    } catch {\n      /* already gone */\n    }\n  });\n  try {\n    return await fn();\n  } finally {\n    dispose();\n    await fs.rm(lockPath, { force: true }).catch(() => undefined);\n  }\n}\n"]}
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/utils/lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AASzC,SAAS,QAAQ,CAAC,GAAW;IAC3B,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAQ,CAA2B,CAAC,IAAI,KAAK,OAAO,CAAC;IACvD,CAAC;AACH,CAAC;AAED,+GAA+G;AAC/G,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAI,YAAoB,EAAE,EAAoB,EAAE,OAAoB,EAAE;IAClG,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC;IACvC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,IAAI,gBAAgB,CAAC,CAAC;IAC/D,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;IACrB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC3B,SAAS,CAAC;QACR,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YACzC,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;YACzE,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;YACjB,MAAM;QACR,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAK,CAA2B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACnD,MAAM,IAAI,iBAAiB,CAAC,IAAI,EAAE,uCAAuC,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;YAC3F,CAAC;YACD,IAAI,KAAc,CAAC;YACnB,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAkC,CAAC;gBAC9F,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;gBACxC,KAAK,GAAG,GAAG,GAAG,OAAO,IAAI,CAAC,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YACjF,CAAC;YAAC,MAAM,CAAC;gBACP,sFAAsF;gBACtF,IAAI,CAAC;oBACH,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC;gBAChE,CAAC;gBAAC,MAAM,CAAC;oBACP,KAAK,GAAG,IAAI,CAAC;gBACf,CAAC;YACH,CAAC;YACD,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBACvC,SAAS;YACX,CAAC;YACD,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,SAAS,EAAE,CAAC;gBACrC,MAAM,IAAI,iBAAiB,CAAC,QAAQ,EAAE,2DAA2D,EAAE;oBACjG,IAAI,EAAE,oCAAoC,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,IAAI,gBAAgB,CAAC,4BAA4B;iBACzI,CAAC,CAAC;YACL,CAAC;YACD,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,EAAE;QAC7B,IAAI,CAAC;YACH,UAAU,CAAC,QAAQ,CAAC,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,kBAAkB;QACpB,CAAC;IACH,CAAC,CAAC,CAAC;IACH,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;YAAS,CAAC;QACT,OAAO,EAAE,CAAC;QACV,MAAM,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAChE,CAAC;AACH,CAAC","sourcesContent":["import { promises as fs, unlinkSync } from 'node:fs';\nimport path from 'node:path';\nimport { DevWorkspaceError } from '../errors/index.js';\nimport { ensureDir } from './fs.js';\nimport { onCleanup } from './cleanup.js';\n\nexport interface LockOptions {\n  timeoutMs?: number;\n  staleMs?: number;\n  /** Lock file name under .devworkspace/local/. Long-running operations use their own lock. */\n  name?: string;\n}\n\nfunction pidAlive(pid: number): boolean {\n  try {\n    process.kill(pid, 0);\n    return true;\n  } catch (e) {\n    return (e as NodeJS.ErrnoException).code === 'EPERM';\n  }\n}\n\n/** Exclusive advisory lock stored under .devworkspace/local/. Stale locks (dead pid or too old) are broken. */\nexport async function withLock<T>(workspaceDir: string, fn: () => Promise<T>, opts: LockOptions = {}): Promise<T> {\n  const timeoutMs = opts.timeoutMs ?? 5000;\n  const staleMs = opts.staleMs ?? 60_000;\n  const dir = path.join(workspaceDir, 'local');\n  const lockPath = path.join(dir, opts.name ?? 'workspace.lock');\n  await ensureDir(dir);\n  const started = Date.now();\n  for (;;) {\n    try {\n      const fh = await fs.open(lockPath, 'wx');\n      await fh.writeFile(JSON.stringify({ pid: process.pid, at: Date.now() }));\n      await fh.close();\n      break;\n    } catch (e) {\n      if ((e as NodeJS.ErrnoException).code !== 'EEXIST') {\n        throw new DevWorkspaceError('IO', 'Could not acquire the workspace lock.', { cause: e });\n      }\n      let stale: boolean;\n      try {\n        const info = JSON.parse(await fs.readFile(lockPath, 'utf8')) as { pid?: number; at?: number };\n        const age = Date.now() - (info.at ?? 0);\n        stale = age > staleMs || (typeof info.pid === 'number' && !pidAlive(info.pid));\n      } catch {\n        // Unreadable lock: another process may be mid-write, so only break it once it is old.\n        try {\n          stale = Date.now() - (await fs.stat(lockPath)).mtimeMs > 2000;\n        } catch {\n          stale = true;\n        }\n      }\n      if (stale) {\n        await fs.rm(lockPath, { force: true });\n        continue;\n      }\n      if (Date.now() - started > timeoutMs) {\n        throw new DevWorkspaceError('LOCKED', 'Another DevWorkspace process is modifying this workspace.', {\n          hint: `Wait for it to finish, or delete ${path.join('.devworkspace', 'local', opts.name ?? 'workspace.lock')} if no process is running.`,\n        });\n      }\n      await new Promise((r) => setTimeout(r, 50));\n    }\n  }\n  const dispose = onCleanup(() => {\n    try {\n      unlinkSync(lockPath);\n    } catch {\n      /* already gone */\n    }\n  });\n  try {\n    return await fn();\n  } finally {\n    dispose();\n    await fs.rm(lockPath, { force: true }).catch(() => undefined);\n  }\n}\n"]}

package/dist/utils/proc.d.ts

@@ -4,12 +4,19 @@ export interface RunResult {
     stdout: string;
     stderr: string;
     timedOut: boolean;
+    aborted?: boolean;
     error?: string;
 }
 export interface RunOptions {
     cwd?: string;
     timeoutMs?: number;
     maxBytes?: number;
+    /** Extra environment variables merged over process.env (undefined values unset the variable). */
+    env?: Record<string, string | undefined>;
+    /** Abort (kill) the process when the signal fires. */
+    signal?: AbortSignal;
+    /** Windows only: pass the argument string through unmodified (used for cmd.exe /c with pre-validated arguments). */
+    windowsVerbatimArguments?: boolean;
 }
 /**
  * Run an executable with an argument array. Never uses a shell, so project- or
@@ -18,5 +25,5 @@ export interface RunOptions {
 export declare function run(command: string, args: string[], opts?: RunOptions): Promise<RunResult>;
 /** Locate an executable on PATH (honouring PATHEXT on Windows) without executing anything. */
 export declare function which(name: string, env?: NodeJS.ProcessEnv): Promise<string | null>;
-/** .cmd/.bat shims need a shell on Windows; we refuse to execute them. */
+/** .cmd/.bat shims need a shell on Windows. They are only run through the validated path in integrations/exec.ts. */
 export declare function isShellShim(file: string): boolean;

package/dist/utils/proc.js

@@ -12,39 +12,62 @@ export function run(command, args, opts = {}) {
         let stdout = '';
         let stderr = '';
         let timedOut = false;
+        let aborted = false;
         let settled = false;
         // eslint-disable-next-line prefer-const -- assigned after spawn; finish() may run first if spawn throws
         let timer;
+        const onAbort = () => {
+            aborted = true;
+            child?.kill();
+        };
         const finish = (r) => {
             if (settled)
                 return;
             settled = true;
             if (timer)
                 clearTimeout(timer);
-            resolve(r);
+            opts.signal?.removeEventListener('abort', onAbort);
+            resolve(aborted ? { ...r, ok: false, aborted: true } : r);
         };
         let child;
+        if (opts.signal?.aborted) {
+            finish({ ok: false, code: null, stdout, stderr, timedOut: false, aborted: true, error: 'aborted' });
+            return;
+        }
         try {
-            child = spawn(command, args, { cwd: opts.cwd, shell: false, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+            const env = opts.env ? { ...process.env, ...opts.env } : process.env;
+            for (const [k, v] of Object.entries(env))
+                if (v === undefined)
+                    delete env[k];
+            child = spawn(command, args, {
+                cwd: opts.cwd,
+                env,
+                shell: false,
+                windowsHide: true,
+                windowsVerbatimArguments: opts.windowsVerbatimArguments,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
         }
         catch (e) {
             finish({ ok: false, code: null, stdout, stderr, timedOut: false, error: e.message });
             return;
         }
+        const c = child;
         timer = setTimeout(() => {
             timedOut = true;
-            child.kill();
+            c.kill();
         }, timeoutMs);
-        child.stdout.on('data', (d) => {
+        opts.signal?.addEventListener('abort', onAbort, { once: true });
+        c.stdout?.on('data', (d) => {
             if (stdout.length < maxBytes)
                 stdout += d.toString('utf8');
         });
-        child.stderr.on('data', (d) => {
+        c.stderr?.on('data', (d) => {
             if (stderr.length < maxBytes)
                 stderr += d.toString('utf8');
         });
-        child.on('error', (e) => finish({ ok: false, code: null, stdout, stderr, timedOut, error: e.message }));
-        child.on('close', (code) => finish({ ok: code === 0 && !timedOut, code, stdout, stderr, timedOut }));
+        c.on('error', (e) => finish({ ok: false, code: null, stdout, stderr, timedOut, error: e.message }));
+        c.on('close', (code) => finish({ ok: code === 0 && !timedOut && !aborted, code, stdout, stderr, timedOut }));
     });
 }
 /** Locate an executable on PATH (honouring PATHEXT on Windows) without executing anything. */
@@ -67,7 +90,7 @@ export async function which(name, env = process.env) {
     }
     return null;
 }
-/** .cmd/.bat shims need a shell on Windows; we refuse to execute them. */
+/** .cmd/.bat shims need a shell on Windows. They are only run through the validated path in integrations/exec.ts. */
 export function isShellShim(file) {
     return /\.(cmd|bat)$/i.test(file);
 }

package/dist/utils/proc.js.map

@@ -1 +1 @@
-{"version":3,"file":"proc.js","sourceRoot":"","sources":["../../src/utils/proc.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from 'node:child_process';\nimport { promises as fs } from 'node:fs';\nimport path from 'node:path';\n\nexport interface RunResult {\n  ok: boolean;\n  code: number | null;\n  stdout: string;\n  stderr: string;\n  timedOut: boolean;\n  error?: string;\n}\n\nexport interface RunOptions {\n  cwd?: string;\n  timeoutMs?: number;\n  maxBytes?: number;\n}\n\n/**\n * Run an executable with an argument array. Never uses a shell, so project- or\n * user-supplied values cannot be interpreted as shell syntax.\n */\nexport function run(command: string, args: string[], opts: RunOptions = {}): Promise<RunResult> {\n  const timeoutMs = opts.timeoutMs ?? 15_000;\n  const maxBytes = opts.maxBytes ?? 4 * 1024 * 1024;\n  return new Promise((resolve) => {\n    let stdout = '';\n    let stderr = '';\n    let timedOut = false;\n    let settled = false;\n    // eslint-disable-next-line prefer-const -- assigned after spawn; finish() may run first if spawn throws\n    let timer: NodeJS.Timeout | undefined;\n    const finish = (r: RunResult): void => {\n      if (settled) return;\n      settled = true;\n      if (timer) clearTimeout(timer);\n      resolve(r);\n    };\n    let child;\n    try {\n      child = spawn(command, args, { cwd: opts.cwd, shell: false, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });\n    } catch (e) {\n      finish({ ok: false, code: null, stdout, stderr, timedOut: false, error: (e as Error).message });\n      return;\n    }\n    timer = setTimeout(() => {\n      timedOut = true;\n      child.kill();\n    }, timeoutMs);\n    child.stdout.on('data', (d: Buffer) => {\n      if (stdout.length < maxBytes) stdout += d.toString('utf8');\n    });\n    child.stderr.on('data', (d: Buffer) => {\n      if (stderr.length < maxBytes) stderr += d.toString('utf8');\n    });\n    child.on('error', (e) => finish({ ok: false, code: null, stdout, stderr, timedOut, error: e.message }));\n    child.on('close', (code) => finish({ ok: code === 0 && !timedOut, code, stdout, stderr, timedOut }));\n  });\n}\n\n/** Locate an executable on PATH (honouring PATHEXT on Windows) without executing anything. */\nexport async function which(name: string, env: NodeJS.ProcessEnv = process.env): Promise<string | null> {\n  const isWin = process.platform === 'win32';\n  const pathVar = env.PATH ?? env.Path ?? '';\n  const exts = isWin ? (env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM').split(';').filter(Boolean) : [''];\n  for (const dir of pathVar.split(path.delimiter).filter(Boolean)) {\n    for (const ext of isWin ? ['', ...exts] : exts) {\n      const candidate = path.join(dir, name + ext);\n      try {\n        const st = await fs.stat(candidate);\n        if (st.isFile()) return candidate;\n      } catch {\n        /* keep looking */\n      }\n    }\n  }\n  return null;\n}\n\n/** .cmd/.bat shims need a shell on Windows; we refuse to execute them. */\nexport function isShellShim(file: string): boolean {\n  return /\\.(cmd|bat)$/i.test(file);\n}\n"]}
+{"version":3,"file":"proc.js","sourceRoot":"","sources":["../../src/utils/proc.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from 'node:child_process';\nimport { promises as fs } from 'node:fs';\nimport path from 'node:path';\n\nexport interface RunResult {\n  ok: boolean;\n  code: number | null;\n  stdout: string;\n  stderr: string;\n  timedOut: boolean;\n  aborted?: boolean;\n  error?: string;\n}\n\nexport interface RunOptions {\n  cwd?: string;\n  timeoutMs?: number;\n  maxBytes?: number;\n  /** Extra environment variables merged over process.env (undefined values unset the variable). */\n  env?: Record<string, string | undefined>;\n  /** Abort (kill) the process when the signal fires. */\n  signal?: AbortSignal;\n  /** Windows only: pass the argument string through unmodified (used for cmd.exe /c with pre-validated arguments). */\n  windowsVerbatimArguments?: boolean;\n}\n\n/**\n * Run an executable with an argument array. Never uses a shell, so project- or\n * user-supplied values cannot be interpreted as shell syntax.\n */\nexport function run(command: string, args: string[], opts: RunOptions = {}): Promise<RunResult> {\n  const timeoutMs = opts.timeoutMs ?? 15_000;\n  const maxBytes = opts.maxBytes ?? 4 * 1024 * 1024;\n  return new Promise((resolve) => {\n    let stdout = '';\n    let stderr = '';\n    let timedOut = false;\n    let aborted = false;\n    let settled = false;\n    // eslint-disable-next-line prefer-const -- assigned after spawn; finish() may run first if spawn throws\n    let timer: NodeJS.Timeout | undefined;\n    const onAbort = (): void => {\n      aborted = true;\n      child?.kill();\n    };\n    const finish = (r: RunResult): void => {\n      if (settled) return;\n      settled = true;\n      if (timer) clearTimeout(timer);\n      opts.signal?.removeEventListener('abort', onAbort);\n      resolve(aborted ? { ...r, ok: false, aborted: true } : r);\n    };\n    let child: ReturnType<typeof spawn> | undefined;\n    if (opts.signal?.aborted) {\n      finish({ ok: false, code: null, stdout, stderr, timedOut: false, aborted: true, error: 'aborted' });\n      return;\n    }\n    try {\n      const env = opts.env ? { ...process.env, ...opts.env } : process.env;\n      for (const [k, v] of Object.entries(env)) if (v === undefined) delete env[k];\n      child = spawn(command, args, {\n        cwd: opts.cwd,\n        env,\n        shell: false,\n        windowsHide: true,\n        windowsVerbatimArguments: opts.windowsVerbatimArguments,\n        stdio: ['ignore', 'pipe', 'pipe'],\n      });\n    } catch (e) {\n      finish({ ok: false, code: null, stdout, stderr, timedOut: false, error: (e as Error).message });\n      return;\n    }\n    const c = child;\n    timer = setTimeout(() => {\n      timedOut = true;\n      c.kill();\n    }, timeoutMs);\n    opts.signal?.addEventListener('abort', onAbort, { once: true });\n    c.stdout?.on('data', (d: Buffer) => {\n      if (stdout.length < maxBytes) stdout += d.toString('utf8');\n    });\n    c.stderr?.on('data', (d: Buffer) => {\n      if (stderr.length < maxBytes) stderr += d.toString('utf8');\n    });\n    c.on('error', (e) => finish({ ok: false, code: null, stdout, stderr, timedOut, error: e.message }));\n    c.on('close', (code) => finish({ ok: code === 0 && !timedOut && !aborted, code, stdout, stderr, timedOut }));\n  });\n}\n\n/** Locate an executable on PATH (honouring PATHEXT on Windows) without executing anything. */\nexport async function which(name: string, env: NodeJS.ProcessEnv = process.env): Promise<string | null> {\n  const isWin = process.platform === 'win32';\n  const pathVar = env.PATH ?? env.Path ?? '';\n  const exts = isWin ? (env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM').split(';').filter(Boolean) : [''];\n  for (const dir of pathVar.split(path.delimiter).filter(Boolean)) {\n    for (const ext of isWin ? ['', ...exts] : exts) {\n      const candidate = path.join(dir, name + ext);\n      try {\n        const st = await fs.stat(candidate);\n        if (st.isFile()) return candidate;\n      } catch {\n        /* keep looking */\n      }\n    }\n  }\n  return null;\n}\n\n/** .cmd/.bat shims need a shell on Windows. They are only run through the validated path in integrations/exec.ts. */\nexport function isShellShim(file: string): boolean {\n  return /\\.(cmd|bat)$/i.test(file);\n}\n"]}

package/docs/architecture.md

@@ -26,7 +26,7 @@ The CLI contains no business logic. `src/index.ts` exports the services so a fut
 | `decisions/`, `sessions/` | Append-only decision records; short session summaries |
 | `security/` | Sensitive-file rules, secret detection/redaction, safe reading |
 | `git/` | Porcelain parsing and state (no mutating Git commands anywhere) |
-| `integrations/` | `Integration` interface + Graphify, Agent Skills, Ponytail, OmniRoute detectors |
+| `integrations/` | Integration manager: one `IntegrationAdapter` per tool (observe, plan, verify), consent levels, file protection, state, runner abstraction (Windows shims, npx) |
 | `agents/` | `AgentAdapter` interface + the Claude adapter (managed `CLAUDE.md` block, skill) |
 | `prompts/` | Onboarding/refresh prompt builders and the behavioural requirement checker |
 | `portability/` | Export bundle format and hostile-input validation |

package/docs/claude.md

@@ -41,6 +41,10 @@ DevWorkspace records what it manages in `project.json` → `managedFiles` (`owne
 - Never claim completion while required checks fail; report `STATUS: BLOCKED` plainly.
 - After meaningful work, record only durable knowledge.
 
+## Integrations
+
+Onboarding tells Claude to run `devworkspace setup --integrations` (after asking you once) rather than installing tools by hand, so installs are previewed, consent-gated, protected and verified the same way whether you or Claude run them. See [integrations.md](integrations.md).
+
 ## Keeping Claude-specific code isolated
 
 Everything Claude-specific lives in `src/agents/claude/`. Core code talks to the `AgentAdapter` interface (`detectExisting`, `plan`), so a Cursor/Codex/Gemini adapter is a new directory implementing the same interface, not a change to core.

package/docs/getting-started.md

@@ -41,7 +41,7 @@ Open `.devworkspace/analysis/onboarding-prompt.md` and paste it into Claude Code
 3. run `devworkspace agent install` (adds a small managed block to `CLAUDE.md` and installs the `devworkspace` skill, preserving anything you wrote),
 4. write concise knowledge into `.devworkspace/context/`,
 5. check the testing contract and record a baseline,
-6. offer to install and verify Graphify, Agent Skills and Ponytail (it asks once; nothing is installed without your yes),
+6. run the integration manager (`devworkspace setup --integrations`) after asking you once; it installs and verifies Graphify, Agent Skills and Ponytail and reports precise statuses,
 7. run `devworkspace doctor` and report unknowns and warnings.
 
 It is told not to modify application source during onboarding.
@@ -52,7 +52,7 @@ It is told not to modify application source during onboarding.
 npx devworkspace doctor
 ```
 
-`READY` means the workspace is healthy, instructions are installed and architecture knowledge exists. Warnings (for example *Graphify: not detected*) tell you exactly what to do next and do not fail the command.
+`Core workspace: READY` means the workspace is healthy, instructions are installed and architecture knowledge exists. Integrations are listed separately with their observed status; anything not `VERIFIED` comes with the exact next step and does not fail the command. Run `npx devworkspace setup --integrations --dry-run` to see what setup would do, and `--yes` to do it.
 
 ## 5. Work normally
 

package/docs/integrations.md

@@ -1,51 +1,116 @@
 # Integrations
 
-Each integration sits behind the `Integration` interface (`src/integrations/types.ts`): `detect(ctx) → IntegrationStatus`. Core code only sees states `READY`, `PARTIAL`, `NOT_DETECTED`, `UNVERIFIED`, `ERROR` plus remediation text. A failing detector degrades to `ERROR` and never breaks a command. Missing integrations are warnings, not failures.
+DevWorkspace can install, verify and repair three tools that the generated Claude instructions rely on. It does this with one command, never assumes success, and never overwrites your files.
 
-Documentation below was read from each project's repository when this version was written. Re-check before relying on it; these projects evolve.
+```bash
+npx devworkspace setup --integrations --dry-run   # see exactly what would run
+npx devworkspace setup --integrations --yes       # do it
+npx devworkspace integrations status              # observe the real state (runs the tools)
+npx devworkspace doctor                           # core workspace + integrations, reported separately
+```
 
-| Integration | Role | Researched against |
+Also: `devworkspace init --with-integrations --yes` (same manager), `devworkspace integrations repair --yes`, and `devworkspace integrations status --restarted` (after you restart Claude Code).
+
+Useful flags: `--only graphify,agent-skills,ponytail` (a subset), `--scope project|user` (default project), `--json` (machine-readable result, progress goes to stderr), `--quick` (status without running the tools).
+
+| Tool | Role | Installed as |
+| --- | --- | --- |
+| [Graphify](https://github.com/Graphify-Labs/graphify) | Structural code graph for navigation | `graphifyy` CLI (per-user) + project skill |
+| [Agent Skills](https://github.com/addyosmani/agent-skills) | Engineering workflows (spec, plan, build, test, review, ship) | Native Claude Code plugin, else portable skills |
+| [Ponytail](https://github.com/DietrichGebert/ponytail) | Quality review and simplification | Native Claude Code plugin, else portable skills |
+| [OmniRoute](https://github.com/diegosouzapw/OmniRoute) | Optional model routing | Never installed; only observed |
+
+## Statuses (what each one means)
+
+Statuses are **observed** by looking at the machine and running the tools. `.devworkspace/state/integrations.json` only records history and is never trusted as proof.
+
+| Status | Meaning |
+| --- | --- |
+| `NOT_INSTALLED` | Nothing found. |
+| `PREREQUISITES_MISSING` | Cannot install automatically; the output says exactly what to install. |
+| `INSTALLING` | A setup run is in progress (a leftover marker means it was interrupted; run `integrations repair --yes`). |
+| `INSTALLED` | Files/config present, **not verified** (quick checks such as `devworkspace status` can never say more). |
+| `VERIFIED` | The tool was run or queried and everything required for its documented capabilities checked out. |
+| `DEGRADED` | Installed but incomplete or unhealthy; the warnings say what is missing (e.g. portable skills have no commands or hooks). |
+| `FAILED` | The last setup attempt failed; the error and next step are shown and remembered. |
+| `RESTART_REQUIRED` | Installed, but Claude Code must be restarted (or `/reload-plugins` run) to load it. Cleared by `integrations status --restarted`. |
+
+"Full integration readiness" is stated only when every **required** integration (Graphify, Agent Skills, Ponytail) is `VERIFIED`. A missing integration never makes the core workspace unhealthy and never changes `doctor`'s exit code unless you pass `--strict` (exit 3).
+
+Exit codes for `setup` / `integrations repair`: `0` every required integration `VERIFIED` or `RESTART_REQUIRED` (or a dry run) · `1` something `FAILED` or a prerequisite is missing · `2` approval needed (nothing risky ran) · `3` finished but not fully verified (`DEGRADED`/`INSTALLED`).
+
+## Consent and scope
+
+Every step has a level. Without `--yes` only **project** steps run; if any step needs more, nothing runs and the plan is printed.
+
+| Level | Examples | Needs `--yes` |
 | --- | --- | --- |
-| Graphify | Structural discovery | `Graphify-Labs/graphify` README (Oct 2026) |
-| Agent Skills | Engineering workflows | `addyosmani/agent-skills` README (Oct 2026) |
-| Ponytail | Quality / simplification review | `DietrichGebert/ponytail` README (Oct 2026) |
-| OmniRoute | Optional model routing | not integrated in V1 |
-| Claude Code | Agent | `code.claude.com` memory and skills docs (Oct 2026) |
+| project | `graphify install --project`, `claude plugin ... --scope project` | no |
+| machine | `uv tool install graphifyy` (your user account, no administrator rights) | yes |
+| user-config | any `--scope user` / `graphify install` (user-level skill) | yes |
+| third-party-code | `npx skills add` (runs a registry package) | yes |
 
-## Graphify
+`--scope project` (default) keeps everything in the repository; `--scope user` installs for all your projects. DevWorkspace never passes `-y` to Claude Code's own plugin installer: if a marketplace wants you to approve a command, setup stops and prints it for you to run.
 
-- **Install (documented):** `uv tool install graphifyy` (or `pipx install graphifyy` / `pip install graphifyy`), then `graphify install` (global) or `graphify install --project` (writes `.claude/skills/graphify/`).
-- **Use:** `/graphify .` in Claude Code builds the graph into `graphify-out/` (`graph.json`, `GRAPH_REPORT.md`, `graph.html`). Queries: `graphify query "…"`, `graphify path "A" "B"`, `graphify explain "…"`. `graphify hook install` auto-rebuilds on commits.
-- **Detection:** `graphify` on PATH, `graphify-out/graph.json`, project/user skill directory. `READY` = (CLI or skill) and a built graph; `PARTIAL` = installed but no graph (or graph without CLI).
-- **Authority:** the graph is an aid. The generated skill tells the agent to confirm in real files; repository evidence wins.
-- **Not done:** DevWorkspace does not run Graphify, build graphs, or parse `graph.json`. `graphify-out/` is excluded from scans.
+Setup is non-interactive. It never prompts, so it cannot hang in CI; when it needs a human it exits `2`/`1` with the exact next step.
+
+## What happens, per tool
+
+### Graphify
+
+1. Reuse an existing `graphify` (PATH, `~/.local/bin`, or where uv/pipx/pip put scripts) after running `graphify --version`.
+2. Otherwise pick an installer: **uv** (`uv tool install graphifyy`), else **pipx** (`pipx install graphifyy`), else the documented **`pip install --user graphifyy`** if a real Python 3.10+ exists. No separate manager is required when Python or uv is present.
+3. Run `graphify install --project` (user scope: `graphify install`).
+4. Verify: executable runs, project skill exists, the skill's recorded version matches the CLI, and, because Graphify's hooks call `graphify` by name, that it is on PATH. If it is not on this process's PATH the status is never a false success, and the advice depends on why: on **Windows**, DevWorkspace reads (never writes) the persistent user and machine PATH from the registry. If the folder is already there, the terminal or VS Code simply started before the change, so the status is `RESTART_REQUIRED` and the fix is to reopen the terminal or restart VS Code (no PATH edit). If it is missing from both, the status is `DEGRADED` with the folder to add. On macOS and Linux, or when the registry cannot be read, the persistent PATH is treated as unknown and the general advice is shown. Quick checks (`devworkspace status`) never query the registry.
+
+Python detection runs `--version` on each candidate (`py -3`, `python3`, `python`). On Windows the Microsoft Store `python` shortcut exists on PATH but is not Python, and is correctly rejected.
+
+**Graphify edits your files.** `graphify install --project` appends a section to `CLAUDE.md`, creates `.claude/CLAUDE.md` and registers Claude Code `PreToolUse` hooks in `.claude/settings.json`. It merges and is idempotent. DevWorkspace snapshots those files first and, if anything you had is missing afterwards, restores them and fails the step. Review `git diff` after setup. Building the graph itself (`/graphify .`) uses the model, so DevWorkspace does not do it.
+
+### Agent Skills and Ponytail
+
+1. **Native plugin** (preferred) when a Claude Code CLI ≥ 2.1.268 is available (PATH, or the binary bundled with the VS Code extension): register the marketplace (`addy-agent-skills`, `ponytail`) by HTTPS git URL, then `claude plugin install <plugin>@<marketplace> --scope project`. Already-registered marketplaces are not added again.
+2. **Portable skills** otherwise, with the documented Skills CLI: `npx skills add <repo> --agent claude-code --skill '*' --copy -y --json` (copied files, telemetry opt-outs set, project scope; `-g` for user scope).
+3. Verify with `claude plugin list --json` (enabled, no load errors, belongs to this project or user scope), or for portable installs by checking the skill folders.
+
+What is reported, honestly:
+
+| | Native plugin | Portable skills |
+| --- | --- | --- |
+| Skills | yes | yes |
+| Slash commands | yes | **no** |
+| Hooks | Ponytail: yes (needs `node` on PATH); Agent Skills: not claimed | **no** |
+| Shared `references/` (Agent Skills) | yes | not installed by the Skills CLI (known upstream limitation, issue #361) → warning |
+| Ponytail's always-on `AGENTS.md` ruleset | n/a | **not installed** (DevWorkspace never edits your `AGENTS.md`) |
+| Resulting status | `RESTART_REQUIRED`, then `VERIFIED` | always `DEGRADED` |
 
-## Agent Skills
+A marketplace being registered does not count as the plugin being installed; the two are checked separately. A same-named skill folder you wrote yourself is never overwritten: setup stops with an explanation.
 
-- **Install (documented):** in Claude Code, `/plugin marketplace add addyosmani/agent-skills` then `/plugin install agent-skills@addy-agent-skills`. The equivalent shell form, which Claude can run for you during onboarding, is `claude plugin marketplace add addyosmani/agent-skills` and `claude plugin install agent-skills@addy-agent-skills`; verify with `claude plugin list`.
-- **Provides:** `/spec`, `/plan`, `/build`, `/test`, `/constraints`, `/review`, `/webperf`, `/code-simplify`, `/ship`, plus auto-activating skills.
-- **Division of labour:** the DevWorkspace skill says *when* (per task type, see [routing](routing.md)); Agent Skills says *how*. Nothing is copied.
-- **Detection:** best effort, searching Claude Code settings/plugin registries for `agent-skills`. Plugin state belongs to Claude Code, so absence is reported as `UNVERIFIED`, not "missing".
+Portable installs record license/attribution in `.devworkspace/THIRD_PARTY_NOTICES.md` (both are MIT; the notice names the copyright holders).
 
-## Ponytail
+## Protection, idempotency and recovery
 
-- **Install (documented):** `/plugin marketplace add DietrichGebert/ponytail`, `/plugin install ponytail@ponytail` (shell form: `claude plugin marketplace add …` / `claude plugin install ponytail@ponytail`). Other agents: copy its `AGENTS.md` or install `skills/ponytail/SKILL.md`.
-- **Commands:** `/ponytail [lite|full|ultra|off]`, `/ponytail-review`, `/ponytail-audit`, `/ponytail-debt`. Optional config `~/.config/ponytail/config.json`, `PONYTAIL_DEFAULT_MODE`.
-- **Use here:** review of meaningful diffs and simplification only. It never substitutes for tests. Strictness maps to `project.json` → `settings.review` (`off` removes the review requirement from new tasks; `light` default; `strict` reserved for stricter policy).
-- **Detection:** plugin mention in settings, `.claude/skills/ponytail`, or `AGENTS.md` mention. Otherwise `UNVERIFIED`.
+- Before each setup run, the files tools may edit (`CLAUDE.md`, `.claude/CLAUDE.md`, `AGENTS.md`, `.claude/settings*.json`) and every existing file under `.claude/skills/` are snapshotted. After each step they are verified: text files may only gain lines, JSON may only gain keys, existing skill files must be byte-identical. Violations are restored and reported.
+- Re-running is safe: verified integrations are skipped, a pending restart is not "fixed" by reinstalling, marketplaces are never added twice, `CLAUDE.md` gets one Graphify section.
+- If a run fails halfway the state is kept (`FAILED`, last error) and the next run resumes from what is observed on disk. If the process was killed, the leftover marker is detected and `integrations repair --yes` finishes the job. Ctrl+C cancels the running child process.
+- Child processes use argument arrays with timeouts (no shell). Windows `.cmd` shims go through a strictly validated `cmd.exe` call that rejects any argument containing shell metacharacters.
+- Tool output is scrubbed (secrets, absolute paths) before it is shown or stored. Credentials are never read.
+- Nothing is ever uninstalled. DevWorkspace has no `uninstall`: removing Claude Code plugins is `claude plugin uninstall`, and Graphify has `graphify uninstall`; run them yourself.
 
-## OmniRoute (optional)
+## Verified vs. assumed (as of 2026-10-09, Windows 11)
 
-Not required, not in the V1 path, no API keys or model configuration. The adapter only reports whether an `omniroute` executable exists. A future provider boundary can build on it.
+Verified **live** on a real machine: `uv tool install graphifyy` and `graphify install --project` (0.9.80 and 0.9.82, files written, merge behaviour, idempotency), `graphify --version`, discovery of uv tool bin directories, Claude Code 2.1.295 `--version`/`plugin list --json`, the failure JSON of `plugin marketplace add`, SSH vs HTTPS clone behaviour and its failure messages.
+Verified with **controlled fake CLIs** (real child processes, `.cmd` shims, folders with spaces) and scripted runners: the successful native-plugin and Skills-CLI paths, restart handling, repair, cancellation, approval prompts. GitHub was unreachable from the build machine for large clones, so a **real end-to-end native plugin install and a real `npx skills add` were not completed**. Their command lines and JSON shapes follow the official documentation and the observed failure output.
+**Not tested:** macOS, Linux, pipx, `pip install --user` for real, Claude Code versions other than 2.1.295.
 
-## Claude Code
+## Limitations
 
-See [claude.md](claude.md).
+- The native-plugin path depends on Claude Code cloning GitHub sources over SSH; without a GitHub SSH key it fails. The setup output then shows the documented fix (`git config --global url."https://github.com/".insteadOf git@github.com:`), which changes your global Git config and is therefore left for you to run.
+- Detection of the Claude Code CLI uses PATH and the VS Code/Cursor extension folders; other installs may need to be on PATH.
+- DevWorkspace cannot tell whether a running Claude Code session has loaded a plugin; `RESTART_REQUIRED` stays until you acknowledge it.
+- Graphify's hooks live in the project's `.claude/settings.json`, so teammates need `graphify` installed too (setup run on their machine does it).
+- OmniRoute is only observed.
 
 ## Adding an integration
 
-1. Implement `Integration` in `src/integrations/<name>.ts` (pure detection, no side effects, timeouts if you spawn anything).
-2. Add it to `INTEGRATIONS` in `src/integrations/index.ts`.
-3. Give it a `usage` string; the Claude skill renders it automatically for non-optional integrations.
-4. Add tests for READY / PARTIAL / NOT_DETECTED and a throwing detector.
-5. Document researched commands and limitations here.
+Implement `IntegrationAdapter` (`src/integrations/types.ts`): `inspect(ctx, deep)` must observe reality (never read the state file as proof) and only return `VERIFIED` when `deep` and every check passed; `plan(ctx, report)` returns steps with a consent `level`, the files they may touch (`protectPaths`) and blockers with exact remediation. Register it in `ADAPTERS`, then test it with `FakeRunner` (see `tests/helpers/fakeRunner.ts`) for: installed, missing, partial, prerequisites missing, timeout, permission denied, cancellation, user-file protection and repeated runs.

package/docs/security.md

@@ -29,7 +29,11 @@ Repository files are untrusted data. The installed instructions and every genera
 
 ## Subprocesses
 
-Only `git` is executed, with argument arrays and `shell: false`, with timeouts and output caps. `.cmd`/`.bat` shims are never executed. Repository scripts are never run by DevWorkspace.
+`git` (read-only) and, during `setup --integrations`, the installers (`uv`, `pipx`, `python -m pip`, `graphify`, `claude`) are executed with argument arrays and `shell: false`, with timeouts and output caps. Windows `.cmd` shims are run only through a validated `cmd.exe` call that rejects arguments containing shell metacharacters. Repository scripts are never run by DevWorkspace.
+
+## Installing third-party tools
+
+`setup --integrations` can install a Python tool (per user), register Claude Code plugins and, as a fallback, run a registry package (`npx skills`). Each step has a consent level and only project-local steps run without `--yes`. Existing `CLAUDE.md`, `.claude/settings*.json`, `AGENTS.md` and skills are snapshotted and verified after every step, and restored on damage. Claude Code's own plugin installer is never given `-y`. The Skills CLI is run with `DISABLE_TELEMETRY=1` and `DO_NOT_TRACK=1`; its other behaviour is its own. Tool output is scrubbed of secrets and absolute paths before it is shown or stored. Plugins and Graphify hooks run code on your machine: review what you approve.
 
 ## Git safety
 

package/docs/testing.md

@@ -15,6 +15,10 @@
 
 `required` is `yes` (always applies to code changes), `context` (only when relevant to the change) or `no`. Entries you or the agent edit by hand get `origin: "user"` and are never overwritten by later analysis.
 
+Every `package.json` in the repository is read (not only the root; manifests in `fixtures/`, `examples/`, `docs/` and `node_modules` are ignored), and each package's commands are recorded **with the directory to run them in** (`cwd`, relative, POSIX), only for scripts that package actually defines. A backend `npm run test:unit` is never mixed up with a frontend `npm test`. Each package uses the package manager its own lockfile indicates. Commands are never executed by DevWorkspace.
+
+Re-running `analyze` keeps any command with `origin: "user"` (confirmed by a person or by Claude during onboarding) exactly as written, even when a later analysis finds nothing; a user command with no `cwd` covers its whole check, one with a `cwd` covers only that directory. `discovery.json` always holds the pure detection; `commands.json` holds the merged contract.
+
 Sources: `package.json` scripts (matched by common names), plus conventions for Python (pytest/ruff/mypy/black/alembic), Go, Rust, Maven and Gradle. npm's default `"no test specified"` placeholder is ignored.
 
 ### Commands are untrusted input
@@ -53,6 +57,8 @@ npm run smoke            # pack → install tarball into clean dirs → run the
 npm run release:check    # the full pre-publish gate; never publishes
 ```
 
+Integration manager tests use a scriptable `FakeRunner`, file-effect emulators that mirror the real Graphify CLI, and a real child-process fake `claude`/`uv`/`graphify` (`tests/helpers/fake-tool.mjs`, run as `.cmd` shims in folders with spaces on Windows). Routine tests never touch your real Claude configuration or install anything on the machine.
+
 Layers: **unit** (pure logic, security, paths incl. `path.win32`, schemas, routing scenarios, prompts), **integration** (command flows through the real CLI in-process with a hermetic home directory), **e2e** (the ten acceptance scenarios, Windows-style paths, large repo simulation, concurrency, hostile imports). Fixtures live in `fixtures/` (Express, React/Vite, Next.js, NestJS, FastAPI, monorepo, no tests, failing tests, existing AI files, prompt injection); scenarios that need Git state, secrets or unusual paths are built at test time.
 
 The generated prompts are tested for *behaviour*, not snapshots: `prompts/requirements.ts` lists what every onboarding/refresh prompt must instruct (untrusted-data rule, no secrets, evidence, git safety, testing contract, completion gate, memory rules, …), and `validatePrompt` is used by the tests and by `doctor`.

package/docs/troubleshooting.md

@@ -8,8 +8,16 @@ Start with `devworkspace doctor`. Every warning/failure includes a remediation l
 | **Git unavailable** | Install Git. DevWorkspace still works but cannot report branch/working-tree state or tracked-secret problems, and Claude cannot protect uncommitted changes. |
 | **Not a Git repository** | Fine. `status` shows `Git: not a repository`. Consider `git init` so changes can be reviewed and reverted. |
 | **"No DevWorkspace found"** | Run `devworkspace init` in the project root. Commands search upward from the current directory; use `--cwd <dir>` if you are elsewhere. |
+| **`setup --integrations` says approval is needed (exit 2)** | Nothing risky ran. Review with `--dry-run`, then re-run with `--yes`. Machine-level (installing the Graphify tool), user-level and registry-package steps always need it. |
+| **`PREREQUISITES_MISSING` for Graphify** | Install uv (`winget install --id astral-sh.uv`) or Python 3.10+ from python.org. On Windows the Microsoft Store `python` shortcut is not Python. Then re-run setup. |
+| **Graphify `RESTART_REQUIRED`: "on your user PATH ... started before that was set"** (Windows) | The folder is already on your persistent PATH; this terminal/VS Code started earlier and still has the old one. Close and reopen the terminal, or restart VS Code (and Claude Code). Do not add it again. |
+| **Graphify `DEGRADED`: not on PATH** | Its Claude Code hooks call `graphify` by name and it is on no PATH (on Windows: not in this terminal and not in your persistent user/machine PATH). Add the folder shown in the next step to PATH (or run `uv tool update-shell` / `pipx ensurepath`) and open a new terminal. |
+| **`RESTART_REQUIRED`** | Restart Claude Code (or run `/reload-plugins`), then `devworkspace integrations status --restarted`. |
+| **Plugin install fails with "Host key verification failed" / "Could not read from remote repository"** | Claude Code cloned the plugin over SSH and you have no GitHub SSH key. Run the documented fix yourself (it edits your global Git config): `git config --global url."https://github.com/".insteadOf git@github.com:`, then re-run setup. |
+| **Plugin or marketplace clone times out** | Slow or blocked access to github.com. Retry later; Claude Code's own timeout can be raised with `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`. Setup resumes from what is already done. |
+| **Agent Skills / Ponytail `DEGRADED` (portable skills)** | The Claude Code CLI was not found, so only portable skills were installed (no slash commands/hooks). Install the native plugin: `claude plugin marketplace add <url> --scope project` then `claude plugin install <plugin>@<marketplace> --scope project`, or put `claude` on PATH and run `devworkspace integrations repair --yes`. |
+| **Setup was interrupted (Ctrl+C, crash)** | Run `devworkspace integrations repair --yes`; it continues from what is observed on disk. Files you own are never left half-edited by DevWorkspace, and `git diff` shows exactly what tools changed. |
 | **Graphify unavailable / no graph** | `uv tool install graphifyy` (or `pipx`), `graphify install --project`, then run `/graphify .` in Claude Code. DevWorkspace keeps working without it. |
-| **Agent Skills / Ponytail "Unverified"** | Claude Code owns plugin state, so this is best-effort. In Claude Code run `/plugin` to see installed plugins, or install: `/plugin marketplace add addyosmani/agent-skills` → `/plugin install agent-skills@addy-agent-skills`; `/plugin marketplace add DietrichGebert/ponytail` → `/plugin install ponytail@ponytail`. |
 | **Claude config conflict** (`agent install` reports `CONFLICT`) | Unbalanced `devworkspace:start/end` markers in `CLAUDE.md`, or a user-authored skill at `.claude/skills/devworkspace/`. Fix/remove the stray marker or rename your skill, then re-run. Nothing was changed. |
 | **Claude ignores my `AGENTS.md`** | Claude reads `AGENTS.md` only when no `CLAUDE.md` exists. `agent install` adds an `@AGENTS.md` import when it creates `CLAUDE.md`; if you created `CLAUDE.md` yourself, add `@AGENTS.md` to it. |
 | **Stale context** | `devworkspace refresh`, then paste `.devworkspace/analysis/refresh-prompt.md` into Claude. Facts without cited `--file` sources can never be proven stale. |
@@ -22,6 +30,8 @@ Start with `devworkspace doctor`. Every warning/failure includes a remediation l
 | **Windows: `EPERM` on write** | Editors, antivirus or indexers can briefly lock files; writes retry for ~2 s. If it persists, close the program holding the file. |
 | **Windows: PowerShell blocks `devworkspace.ps1`** | `npm` creates `.cmd` and `.ps1` shims. Run via `devworkspace.cmd`, `npx devworkspace`, or relax the execution policy for your user (`Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`). |
 | **`.devworkspace` not appearing in Git** | The root `.gitignore` ignores it. Remove that rule; `.devworkspace/.gitignore` already excludes the machine-local parts. |
+| **`doctor` warns "package manifest(s) the last analysis did not record"** | The analysis predates nested-package detection. Run `devworkspace analyze`; commands you confirmed earlier are kept. |
+| **`doctor` warns "No ecosystem was detected" or "No verification commands"** | The analyzer found no recognised manifest or scripts. Add them, or write the commands in `.devworkspace/context/commands.json` (`"origin": "user"`, optional `"cwd": "backend"`). If the project intentionally has none, set `"acknowledgeNoVerification": true` under `settings` in `.devworkspace/project.json`. |
 | **Analysis seems incomplete** | `status`/`doctor` says "partial" when file or depth limits were hit. Raise `settings.maxFiles` in `project.json` or add `.devworkspaceignore` entries for generated folders. |
 
 Add `--debug` to any command for stack traces and debug logs (secrets are still redacted).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devworkspace",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Project-local AI engineering workspace: deterministic repository discovery, portable project knowledge, tasks, decisions and verification gates for AI coding agents.",
   "type": "module",
   "bin": {

package/dist/integrations/agent-skills.d.ts

@@ -1,10 +0,0 @@
-import type { Integration } from './types.js';
-/**
- * Agent Skills is distributed as a Claude Code plugin. Documented install:
- *   /plugin marketplace add addyosmani/agent-skills
- *   /plugin install agent-skills@addy-agent-skills
- * Its slash commands (/spec /plan /build /test /review /code-simplify /ship) provide the HOW;
- * DevWorkspace's generated skill only decides WHEN to use them.
- * Plugin state is owned by Claude Code, so detection is best effort and reported as UNVERIFIED when not found.
- */
-export declare const agentSkills: Integration;

package/dist/integrations/agent-skills.js

@@ -1,45 +0,0 @@
-import { claudeConfigMentions } from './probe.js';
-const DOCS = 'https://github.com/addyosmani/agent-skills';
-/**
- * Agent Skills is distributed as a Claude Code plugin. Documented install:
- *   /plugin marketplace add addyosmani/agent-skills
- *   /plugin install agent-skills@addy-agent-skills
- * Its slash commands (/spec /plan /build /test /review /code-simplify /ship) provide the HOW;
- * DevWorkspace's generated skill only decides WHEN to use them.
- * Plugin state is owned by Claude Code, so detection is best effort and reported as UNVERIFIED when not found.
- */
-export const agentSkills = {
-    id: 'agent-skills',
-    name: 'Agent Skills',
-    optional: false,
-    usage: 'Use the Agent Skills workflows for engineering methodology: /spec (requirements), /plan (task breakdown), /build (implementation), ' +
-        '/test (verification), /review (review gates), /code-simplify (reduce complexity), /ship (release). Do not re-implement them from memory; invoke them.',
-    async detect(ctx) {
-        const hit = await claudeConfigMentions(ctx, 'agent-skills');
-        if (hit) {
-            return {
-                id: 'agent-skills',
-                name: 'Agent Skills',
-                optional: false,
-                state: 'READY',
-                details: [`referenced in Claude Code config (${hit})`],
-                remediation: [],
-                docsUrl: DOCS,
-            };
-        }
-        return {
-            id: 'agent-skills',
-            name: 'Agent Skills',
-            optional: false,
-            state: 'UNVERIFIED',
-            details: ['not found in Claude Code settings; plugin state is held by Claude Code so this check is best-effort'],
-            remediation: [
-                'In Claude Code run: /plugin marketplace add addyosmani/agent-skills',
-                'Then: /plugin install agent-skills@addy-agent-skills',
-                'Verify with /plugin, or by confirming /spec and /review appear in the slash-command list.',
-            ],
-            docsUrl: DOCS,
-        };
-    },
-};
-//# sourceMappingURL=agent-skills.js.map

package/dist/integrations/agent-skills.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"agent-skills.js","sourceRoot":"","sources":["../../src/integrations/agent-skills.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,IAAI,GAAG,4CAA4C,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAgB;IACtC,EAAE,EAAE,cAAc;IAClB,IAAI,EAAE,cAAc;IACpB,QAAQ,EAAE,KAAK;IACf,KAAK,EACH,qIAAqI;QACrI,uJAAuJ;IACzJ,KAAK,CAAC,MAAM,CAAC,GAAG;QACd,MAAM,GAAG,GAAG,MAAM,oBAAoB,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QAC5D,IAAI,GAAG,EAAE,CAAC;YACR,OAAO;gBACL,EAAE,EAAE,cAAc;gBAClB,IAAI,EAAE,cAAc;gBACpB,QAAQ,EAAE,KAAK;gBACf,KAAK,EAAE,OAAO;gBACd,OAAO,EAAE,CAAC,qCAAqC,GAAG,GAAG,CAAC;gBACtD,WAAW,EAAE,EAAE;gBACf,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QACD,OAAO;YACL,EAAE,EAAE,cAAc;YAClB,IAAI,EAAE,cAAc;YACpB,QAAQ,EAAE,KAAK;YACf,KAAK,EAAE,YAAY;YACnB,OAAO,EAAE,CAAC,qGAAqG,CAAC;YAChH,WAAW,EAAE;gBACX,qEAAqE;gBACrE,sDAAsD;gBACtD,2FAA2F;aAC5F;YACD,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;CACF,CAAC","sourcesContent":["import type { Integration, IntegrationStatus } from './types.js';\nimport { claudeConfigMentions } from './probe.js';\n\nconst DOCS = 'https://github.com/addyosmani/agent-skills';\n\n/**\n * Agent Skills is distributed as a Claude Code plugin. Documented install:\n *   /plugin marketplace add addyosmani/agent-skills\n *   /plugin install agent-skills@addy-agent-skills\n * Its slash commands (/spec /plan /build /test /review /code-simplify /ship) provide the HOW;\n * DevWorkspace's generated skill only decides WHEN to use them.\n * Plugin state is owned by Claude Code, so detection is best effort and reported as UNVERIFIED when not found.\n */\nexport const agentSkills: Integration = {\n  id: 'agent-skills',\n  name: 'Agent Skills',\n  optional: false,\n  usage:\n    'Use the Agent Skills workflows for engineering methodology: /spec (requirements), /plan (task breakdown), /build (implementation), ' +\n    '/test (verification), /review (review gates), /code-simplify (reduce complexity), /ship (release). Do not re-implement them from memory; invoke them.',\n  async detect(ctx): Promise<IntegrationStatus> {\n    const hit = await claudeConfigMentions(ctx, 'agent-skills');\n    if (hit) {\n      return {\n        id: 'agent-skills',\n        name: 'Agent Skills',\n        optional: false,\n        state: 'READY',\n        details: [`referenced in Claude Code config (${hit})`],\n        remediation: [],\n        docsUrl: DOCS,\n      };\n    }\n    return {\n      id: 'agent-skills',\n      name: 'Agent Skills',\n      optional: false,\n      state: 'UNVERIFIED',\n      details: ['not found in Claude Code settings; plugin state is held by Claude Code so this check is best-effort'],\n      remediation: [\n        'In Claude Code run: /plugin marketplace add addyosmani/agent-skills',\n        'Then: /plugin install agent-skills@addy-agent-skills',\n        'Verify with /plugin, or by confirming /spec and /review appear in the slash-command list.',\n      ],\n      docsUrl: DOCS,\n    };\n  },\n};\n"]}

package/dist/integrations/graphify.d.ts

@@ -1,7 +0,0 @@
-import type { Integration } from './types.js';
-/**
- * Graphify builds a queryable knowledge graph in graphify-out/ and registers a Claude Code skill.
- * Documented install: `uv tool install graphifyy` (or pipx/pip), then `graphify install --project`.
- * DevWorkspace only detects it and tells the agent when to use it; it never re-implements graph building.
- */
-export declare const graphify: Integration;

package/dist/integrations/graphify.js

@@ -1,54 +0,0 @@
-import { promises as fs } from 'node:fs';
-import path from 'node:path';
-import { skillDirExists } from './probe.js';
-const DOCS = 'https://github.com/Graphify-Labs/graphify';
-/**
- * Graphify builds a queryable knowledge graph in graphify-out/ and registers a Claude Code skill.
- * Documented install: `uv tool install graphifyy` (or pipx/pip), then `graphify install --project`.
- * DevWorkspace only detects it and tells the agent when to use it; it never re-implements graph building.
- */
-export const graphify = {
-    id: 'graphify',
-    name: 'Graphify',
-    optional: false,
-    usage: 'For "where is X / what depends on Y" questions, query the Graphify graph first (graphify query "<question>", graphify path, graphify explain) ' +
-        'or use the /graphify skill. The graph is a navigation aid, not a source of truth: confirm in the actual files before relying on it.',
-    async detect(ctx) {
-        const details = [];
-        const remediation = [];
-        const cli = await ctx.which('graphify');
-        const skill = await skillDirExists(ctx, 'graphify');
-        let graphBuilt = false;
-        try {
-            const st = await fs.stat(path.join(ctx.root, 'graphify-out', 'graph.json'));
-            graphBuilt = st.isFile();
-            if (graphBuilt)
-                details.push(`graph built (graphify-out/graph.json, updated ${st.mtime.toISOString().slice(0, 10)})`);
-        }
-        catch {
-            /* not built */
-        }
-        if (cli)
-            details.push('graphify CLI on PATH');
-        if (skill)
-            details.push(`Claude skill installed (${skill})`);
-        let state;
-        if ((cli || skill) && graphBuilt)
-            state = 'READY';
-        else if (cli || skill) {
-            state = 'PARTIAL';
-            details.push('no graph built yet');
-            remediation.push('In Claude Code run: /graphify .   (builds graphify-out/graph.json)');
-        }
-        else if (graphBuilt) {
-            state = 'PARTIAL';
-            remediation.push('Install the CLI: uv tool install graphifyy   (or pipx install graphifyy), then: graphify install --project');
-        }
-        else {
-            state = 'NOT_DETECTED';
-            remediation.push('Install: uv tool install graphifyy   (or pipx install graphifyy)', 'Register for this project: graphify install --project', 'Then in Claude Code run: /graphify .');
-        }
-        return { id: 'graphify', name: 'Graphify', optional: false, state, details, remediation, docsUrl: DOCS };
-    },
-};
-//# sourceMappingURL=graphify.js.map