insta 0.0.58 → 0.0.60

package/dist/commands/observe.js

@@ -1,15 +1,49 @@
 // `insta observe` — the local credential-audit hook. install wires a PostToolUse hook into the
 // agent harness; report renders the local audit; sync uploads findings into the project timeline
 // (idempotent via a stable dedup key, matching the platform's audit-event ingest).
+import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { installObserve, uninstallObserve } from '../observe/install.js';
+import { untrackHint } from '../gitignore.js';
+import { findProjectRoot } from '../config.js';
 import { renderReport } from '../observe/report.js';
 import { ApiClient, requireProject } from '../api.js';
 import { info, printJson } from '../util.js';
+// Where the audit lives: the hook records at the directory it is materialized in
+// (<root>/.insta/observe/hook.js — see projectRootFor), so report/sync must anchor on exactly
+// that: the NEAREST materialized hook above cwd, which is what the Codex wrapper and the Claude
+// entry run. The link file is only a fallback for a directory where no hook exists yet (it is
+// where the next install will land), then cwd (→ "audit log is empty"). Preferring the link file
+// would break the moment the two diverge — e.g. a hook materialized below a linked parent —
+// because the reader would look where the writer never writes.
+export async function auditRoot(cwd = process.cwd()) {
+    const hook = nearestHookRoot(cwd);
+    if (hook)
+        return hook;
+    return (await findProjectRoot(cwd)) ?? cwd;
+}
+/** Nearest ancestor (or cwd) holding a materialized hook, or null. */
+export function nearestHookRoot(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        if (existsSync(join(dir, '.insta', 'observe', 'hook.js')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** Where `install` materializes: the linked project root when inside one (so a re-link or
+ *  `observe install` from a subdirectory refreshes the project's hook instead of minting a second
+ *  one the readers never look at — same rule as writeProject), else cwd. */
+export async function installRoot(cwd = process.cwd()) {
+    return (await findProjectRoot(cwd)) ?? cwd;
+}
 async function readAudit() {
     try {
-        const txt = await readFile(join(process.cwd(), '.insta', 'audit.jsonl'), 'utf8');
+        const txt = await readFile(join(await auditRoot(), '.insta', 'audit.jsonl'), 'utf8');
         return txt.split('\n').filter(Boolean).map((l) => JSON.parse(l));
     }
     catch {
@@ -24,13 +58,19 @@ function* chunk(a, n) {
         yield a.slice(i, i + n);
 }
 export async function observeInstall() {
-    const res = installObserve({ cwd: process.cwd() });
-    info(`installed observe hook (claude: ${res.claude}, codex: ${res.codex}) → ./.insta/observe`);
+    const root = await installRoot();
+    const res = installObserve({ cwd: root });
+    info(`installed observe hook (claude: ${res.claude}, codex: ${res.codex}) → ${join(root, '.insta', 'observe')}`);
+    if (res.ignored.length)
+        info(`  .gitignore += ${res.ignored.join(', ')}`);
+    const hint = untrackHint(res.tracked);
+    if (hint)
+        info(hint);
     info('it scans agent tool-use for credential exposure; findings append to ./.insta/audit.jsonl');
     info('run `insta observe report` to review, `insta observe sync` to upload to the project timeline');
 }
 export async function observeUninstall() {
-    uninstallObserve(process.cwd());
+    uninstallObserve(await installRoot());
     info('uninstalled observe hook');
 }
 export async function observeReport(opts) {

package/dist/commands/project.js

@@ -3,6 +3,8 @@ import { ApiClient, requireProject } from '../api.js';
 import { writeProject } from '../config.js';
 import { info, die, printJson, handleApproval, renderNextActions } from '../util.js';
 import { installObserve } from '../observe/install.js';
+import { installRoot } from './observe.js';
+import { untrackHint } from '../gitignore.js';
 import { installSkills } from '../ensure-skills.js';
 // Generic directory names that make a useless project name ("projects", "~", "tmp", …). When the
 // cwd basename is one of these we DON'T invent a name — we guide the user to name it (or let their
@@ -13,14 +15,20 @@ const GENERIC_DIRS = new Set([
     'app', 'apps', 'users', 'user', 'bin', 'new', 'test', 'tests',
 ]);
 // Best-effort: wire the credential-audit hook into the project (no-op if assets aren't built).
+// Anchored at the linked project root (writeProject just updated it), not cwd: a re-link from a
+// subdirectory must refresh the project's hook, not mint a second one the readers never see.
 // quiet: with --json the install still runs, but its note moves to stderr (stdout is JSON-only).
-function tryInstallObserve(quiet = false) {
+async function tryInstallObserve(quiet = false) {
     try {
-        const r = installObserve({ cwd: process.cwd() });
-        if (r.claude || r.codex) {
-            const line = '  installed observe hook (credential audit) → ./.insta/observe';
-            quiet ? process.stderr.write(line + '\n') : info(line);
-        }
+        const r = installObserve({ cwd: await installRoot() });
+        const say = (line) => (quiet ? process.stderr.write(line + '\n') : info(line));
+        if (r.claude || r.codex)
+            say('  installed observe hook (credential audit) → ./.insta/observe');
+        if (r.ignored.length)
+            say(`  .gitignore += ${r.ignored.join(', ')}`);
+        const hint = untrackHint(r.tracked);
+        if (hint)
+            say(hint);
     }
     catch { /* assets missing (dev/unbuilt) — skip silently */ }
 }
@@ -77,7 +85,7 @@ export async function projectCreate(name, opts) {
         info(`  linked ./.insta/project.json (branch ${out.defaultBranch.name})`);
         renderNextActions(out.nextActions);
     }
-    tryInstallObserve(opts.json);
+    await tryInstallObserve(opts.json);
     await installSkills({ cwd: process.cwd(), print: skillsPrint(opts.json) });
 }
 export async function projectList(opts) {
@@ -99,7 +107,7 @@ export async function projectLink(id, opts = {}) {
         printJson({ project, linked: { projectId: project.id, orgId: project.org_id, branch: 'main' } });
     else
         info(`linked project ${project.id} (${project.name})`);
-    tryInstallObserve(opts.json);
+    await tryInstallObserve(opts.json);
     await installSkills({ cwd: process.cwd(), print: skillsPrint(opts.json) });
 }
 export async function projectDelete(opts) {

package/dist/ensure-skills.js

@@ -6,15 +6,19 @@
 // repo moved) prints a manual fallback and never blocks or fails the host command — same contract
 // as the observe-hook install.
 import { spawn } from 'node:child_process';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
 import { resolveEnv } from './config.js';
 import { resolveSpawnable } from './commands/setup.js';
 import { DEFAULT_ENV, ENVS } from './env.js';
+import { alreadyTracked, ensureGitignore, untrackHint } from './gitignore.js';
+export { ensureGitignore } from './gitignore.js';
 // Where `npx skills add` drops skills for the agents we pin below: Claude Code → .claude/skills/,
-// Codex → .agents/skills/ (.github/skills/ is the third well-known dir). These are regenerable
-// agent context, not the developer's source — keep them out of git.
-const SKILL_DIRS = ['.claude/skills/', '.agents/skills/', '.github/skills/'];
+// Codex → .agents/skills/ (.github/skills/ is the third well-known dir), plus the skills-lock.json
+// it writes at the project root. All regenerable agent context, not the developer's source — keep
+// them out of git. The lock goes too: its payload is already ignored, it pins only a content hash
+// (not the prod/staging source this CLI resolves per environment), and `insta project link` is
+// the restore path — so a committed lock would be a lockfile for nothing.
+const SKILL_DIRS = ['.claude/skills/', '.agents/skills/', '.github/skills/', 'skills-lock.json'];
+const GITIGNORE_COMMENT = '# InstaCloud: agent skills installed by `npx skills add` (regenerable, not source)';
 // `skills` prints a full-screen ASCII banner at the top of every `add`, so our 3 invocations
 // would stack 3 banners. It skips the banner when it detects an agent driving it rather than a
 // human — AI_AGENT is its first-checked signal (any non-empty value ⇒ agent mode). Setting it is
@@ -76,15 +80,27 @@ export async function installSkills(deps) {
         }
         catch { /* keep production defaults */ }
         print('  installing related agent skills (insta, tigris, better-auth) …');
+        let installed = 0;
         for (const s of targets) {
             // Don't stream: the `skills` tool's clack UI (clone spinner, banners) is noise. Run it
             // silent (stdio 'ignore') and let the per-skill ✓/failed line below be the clean output —
             // it appears as each skill finishes, so there's still live progress. (Also avoids the
             // child inheriting a piped stdin.)
             const r = await run('npx', s.args);
+            if (r.ok)
+                installed++;
             print(r.ok ? `  ${s.label} ✓` : `  ${s.label} failed — add manually: npx ${s.args.join(' ')}`);
         }
-        const added = ensureGitignore(deps.cwd, SKILL_DIRS);
+        // The already-tracked hint is independent of this run: a repo that committed the skill dirs
+        // or the lock months ago needs the `git rm --cached` line whether or not today's adds worked.
+        const hint = untrackHint(alreadyTracked(deps.cwd, SKILL_DIRS));
+        if (hint)
+            print(hint);
+        // The ignore entries only when something was actually written: an offline run that failed
+        // every add has no new skill dirs or lock, and a `.gitignore +=` line would claim otherwise.
+        if (installed === 0)
+            return;
+        const added = ensureGitignore(deps.cwd, SKILL_DIRS, GITIGNORE_COMMENT);
         if (added.length)
             print(`  .gitignore += ${added.join(', ')}`);
     }
@@ -92,18 +108,4 @@ export async function installSkills(deps) {
         /* best-effort convenience — never block the host command */
     }
 }
-// Append any missing entries to the project's ./.gitignore (creating it if absent). Idempotent:
-// entries already present are left alone. Returns the entries it added.
-export function ensureGitignore(cwd, entries) {
-    const p = join(cwd, '.gitignore');
-    const existing = existsSync(p) ? readFileSync(p, 'utf8') : '';
-    const have = new Set(existing.split('\n').map((l) => l.trim()));
-    const missing = entries.filter((e) => !have.has(e));
-    if (missing.length === 0)
-        return [];
-    const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
-    const comment = '# InstaCloud: agent skills installed by `npx skills add` (regenerable, not source)';
-    writeFileSync(p, existing + `${prefix}\n${comment}\n${missing.join('\n')}\n`);
-    return missing;
-}
 //# sourceMappingURL=ensure-skills.js.map

package/dist/gitignore.js

@@ -0,0 +1,45 @@
+// Shared `.gitignore` maintenance for files the CLI writes into a project that are not the
+// developer's source (installed skills, observe-hook state). The rule: whatever writes a
+// regenerable or machine-local file adds its ignore entry in the same step, so `git status` never
+// surfaces it as a surprise — the same convention as `insta secrets` for .env.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// Append any missing entries to the project's ./.gitignore (creating it if absent). Idempotent:
+// entries already present (exact line match) are left alone; a block gets one `comment` header
+// the first time it contributes. Returns the entries it added.
+export function ensureGitignore(cwd, entries, comment) {
+    const p = join(cwd, '.gitignore');
+    const existing = existsSync(p) ? readFileSync(p, 'utf8') : '';
+    const have = new Set(existing.split('\n').map((l) => l.trim()));
+    const missing = entries.filter((e) => !have.has(e));
+    if (missing.length === 0)
+        return [];
+    const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
+    const header = comment && !have.has(comment) ? `${comment}\n` : '';
+    writeFileSync(p, existing + `${prefix}\n${header}${missing.join('\n')}\n`);
+    return missing;
+}
+// An ignore entry does nothing for a path git already tracks — and the repos that most need these
+// entries are the ones where the files were committed before the CLI ignored them. Returns the
+// entries (as given) that have tracked files under them, so the caller can print the one hint
+// that fixes it (`git rm -r --cached …`). Empty when git is absent or cwd is not a repo.
+export function alreadyTracked(cwd, entries) {
+    if (entries.length === 0)
+        return [];
+    try {
+        const r = spawnSync('git', ['ls-files', '-z', '--', ...entries], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+        if (r.status !== 0 || !r.stdout)
+            return [];
+        const tracked = r.stdout.split('\0').filter(Boolean);
+        return entries.filter((e) => tracked.some((t) => t === e || t.startsWith(e.endsWith('/') ? e : `${e}/`)));
+    }
+    catch {
+        return [];
+    }
+}
+/** The one-line hint for `alreadyTracked` hits, or null when there are none. */
+export function untrackHint(tracked) {
+    return tracked.length ? `  already tracked by git — to stop committing: git rm -r --cached ${tracked.join(' ')}` : null;
+}
+//# sourceMappingURL=gitignore.js.map

package/dist/observe/hook.js

@@ -1,7 +1,7 @@
 // PostToolUse hook: reads a tool-use event on stdin (Claude Code / Codex), scans every string
 // surface for credential exposure, and appends findings to ./.insta/audit.jsonl. Ported from firth.
 import { appendFileSync, mkdirSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { scanEvent } from './scanner.js';
 export function recordFindings(event, baseDir) {
@@ -38,6 +38,19 @@ async function readStdin() {
         chunks.push(c);
     return Buffer.concat(chunks).toString('utf8');
 }
+// Where findings go. The materialized hook lives at <project root>/.insta/observe/hook.js, so its
+// own entry path names the linked project root — the one directory whose .insta/audit.jsonl is
+// gitignored and that `insta observe report` reads. Anything else (the harness's project-dir env,
+// the event cwd) is only a guess: Codex passes the SESSION cwd, which in a monorepo can be a
+// subdirectory of the project, and writing there would leave an unignored audit log behind.
+export function projectRootFor(entry, env, eventCwd) {
+    if (entry) {
+        const dir = resolve(dirname(entry));
+        if (basename(dir) === 'observe' && basename(dirname(dir)) === '.insta')
+            return dirname(dirname(dir));
+    }
+    return env.CLAUDE_PROJECT_DIR || eventCwd || '.';
+}
 export async function main() {
     let event;
     try {
@@ -46,7 +59,7 @@ export async function main() {
     catch {
         process.exit(0);
     }
-    const base = process.env.CLAUDE_PROJECT_DIR || event.cwd || '.';
+    const base = projectRootFor(process.argv[1], process.env, event.cwd);
     try {
         recordFindings(event, base);
     }

package/dist/observe/install.js

@@ -3,7 +3,14 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { alreadyTracked, ensureGitignore } from '../gitignore.js';
 const MARKER = 'insta-observe';
+// What the hook leaves under ./.insta that is machine-local, not project source: observe/ is a
+// copy of this CLI version's hook + scanner (regenerated by every `project link`), and
+// audit.jsonl is this machine's findings (fingerprints + redacted context — `insta observe sync`
+// is the share path). ./.insta/project.json stays committable: it is the team's project binding.
+const LOCAL_PATHS = ['.insta/observe/', '.insta/audit.jsonl'];
+const GITIGNORE_COMMENT = '# InstaCloud: local observe-hook state (regenerated per machine, not source)';
 const DEFAULT_ASSET_DIR = dirname(fileURLToPath(import.meta.url)); // built: cli/dist/observe
 function cliVersion() {
     try {
@@ -64,12 +71,45 @@ function claudeEntry() {
     return { matcher: '*', hooks: [{ type: 'command',
                 command: `[ ! -f ${hook} ] || node ${hook}`, timeout: 15, _insta: MARKER }] };
 }
-function codexEntry(cwd) {
-    const abs = join(cwd, '.insta', 'observe', 'hook.js'); // Codex doesn't expand ${CLAUDE_PROJECT_DIR}; use an absolute path
-    return { matcher: '*', hooks: [{ type: 'command', command: `node ${JSON.stringify(abs)}`, timeout: 15, _insta: MARKER }] };
+// The Codex hook command. Constraints that rule out every simpler form:
+//  - no absolute path: it made .codex/hooks.json machine-specific (a teammate committing it shipped
+//    /Users/<author>/… to every clone, where node failed after each tool call);
+//  - not `git rev-parse --show-toplevel`: the insta project root is wherever `project link` ran,
+//    which in a monorepo is below the git root (`findProjectRoot` climbs for .insta/project.json
+//    for exactly that reason), so the hook would silently never fire there;
+//  - no POSIX shell syntax: with no `commandWindows` override Codex hands `command` verbatim to
+//    cmd.exe on Windows, where `[ ! -f … ]` / `$(…)` are parse errors — after every tool call.
+// So: one shell-neutral `node -e` that climbs from the session cwd (Codex runs project hooks with
+// the project as cwd) to the nearest .insta/observe/hook.js and runs it with stdin passed through;
+// a fresh clone with no ./.insta anywhere above is a silent no-op. The script must stay free of
+// characters either shell rewrites inside double quotes: `$` and backticks (sh), `%` and `!`
+// (cmd.exe), and `"` (both). Codex has each user trust the entry before it runs, so shareable is safe.
+// Exit code: the hook's own status when it ran; 0 when it could not be started or was killed
+// (status null) — every other arm of this install is silent best-effort, and Codex reports any
+// non-zero exit as a failed hook after EVERY tool call, which is worse than a missed audit line.
+const CODEX_HOOK_SCRIPT = [
+    "const f=require('fs'),p=require('path'),c=require('child_process');",
+    'let d=process.cwd();',
+    'for(;;){',
+    "const h=p.join(d,'.insta/observe/hook.js');",
+    "if(f.existsSync(h)){const r=c.spawnSync(process.execPath,[h],{stdio:'inherit'});process.exitCode=r.status===null?0:r.status;break}",
+    'const u=p.dirname(d);if(u===d)break;d=u}',
+].join('');
+function codexEntry() {
+    return { matcher: '*', hooks: [{ type: 'command',
+                command: `node -e "${CODEX_HOOK_SCRIPT}"`, timeout: 15, _insta: MARKER }] };
 }
 export function installObserve(opts) {
     materialize(opts.cwd, opts.assetDir ?? DEFAULT_ASSET_DIR); // hook required → let a missing asset throw to the caller
+    // Ignore the local state in the same step that creates it, so nobody discovers it via
+    // `git status`. Best-effort: an unwritable .gitignore must not fail the hook install.
+    // (Uninstall deliberately leaves the entries: a stale audit.jsonl should stay ignored.)
+    let ignored = [];
+    try {
+        ignored = ensureGitignore(opts.cwd, LOCAL_PATHS, GITIGNORE_COMMENT);
+    }
+    catch { /* keep going */ }
+    const tracked = alreadyTracked(opts.cwd, LOCAL_PATHS);
     let claude = false;
     let codex = false;
     try {
@@ -78,11 +118,11 @@ export function installObserve(opts) {
     }
     catch { /* skip malformed */ }
     try {
-        registerHarness(join(opts.cwd, '.codex', 'hooks.json'), codexEntry(opts.cwd));
+        registerHarness(join(opts.cwd, '.codex', 'hooks.json'), codexEntry());
         codex = true;
     }
     catch { /* skip malformed */ }
-    return { claude, codex };
+    return { claude, codex, ignored, tracked };
 }
 export function uninstallObserve(cwd) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "insta",
-  "version": "0.0.58",
+  "version": "0.0.60",
   "type": "module",
   "description": "InstaCloud CLI — a thin client of the platform control-plane API.",
   "keywords": [