insta 0.0.57 → 0.0.59

package/README.md

@@ -233,7 +233,7 @@ build never reaches a production installer.
 | `INSTA_PROJECT_ID` · `INSTA_ORG_ID` · `INSTA_BRANCH` | Target a project, org or branch without linking |
 | `INSTA_PASSWORD` | Password for non-interactive login |
 | `INSTA_NO_AUTOUPDATE` | Disable self-update |
-| `INSTA_NO_TELEMETRY` · `DO_NOT_TRACK` | Disable usage analytics. Each command sends one event (command, flags, outcome, version, OS) to the same PostHog project as the console. Only ids, enums and numbers among the arguments are kept — names, branches, keys, paths, secret values, free text and error messages never leave the machine; custom API hosts report nothing |
+| `INSTA_NO_TELEMETRY` · `DO_NOT_TRACK` | Disable usage analytics. Each command sends one event (command, flags, outcome, version, OS) to the same PostHog project as the console. Only ids, enums and numbers among the arguments are kept — names, branches, keys, paths, secret values, free text and error messages never leave the machine; custom API hosts report nothing. Before you sign in, events carry a random id stored in `~/.insta/telemetry.json`; the first command after you sign in sends one extra event merging that id into your account, and the first command after the session ends (logout, `env use`) retires it |
 
 ## Agent skills
 

package/dist/commands/observe.js

@@ -1,15 +1,37 @@
 // `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 the same
+// thing. The link file is the usual root, but a standalone `insta observe install` in an
+// unlinked directory has no project.json — climb for the hook itself then, so both halves agree
+// from any subdirectory. Falls back to cwd when neither exists (→ "audit log is empty").
+export async function auditRoot(cwd = process.cwd()) {
+    const linked = await findProjectRoot(cwd);
+    if (linked)
+        return linked;
+    let dir = resolve(cwd);
+    for (;;) {
+        if (existsSync(join(dir, '.insta', 'observe', 'hook.js')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return cwd;
+        dir = parent;
+    }
+}
 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 {
@@ -26,6 +48,11 @@ function* chunk(a, n) {
 export async function observeInstall() {
     const res = installObserve({ cwd: process.cwd() });
     info(`installed observe hook (claude: ${res.claude}, codex: ${res.codex}) → ./.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');
 }

package/dist/commands/project.js

@@ -3,6 +3,7 @@ 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 { 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
@@ -17,10 +18,14 @@ const GENERIC_DIRS = new Set([
 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 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 */ }
 }

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,34 +80,30 @@ 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);
+        // Only when something was actually written: an offline run that failed every add has no
+        // skill dirs or lock to ignore, and a `.gitignore +=` line there would claim otherwise.
+        if (installed === 0)
+            return;
+        const added = ensureGitignore(deps.cwd, SKILL_DIRS, GITIGNORE_COMMENT);
         if (added.length)
             print(`  .gitignore += ${added.join(', ')}`);
+        const hint = untrackHint(alreadyTracked(deps.cwd, SKILL_DIRS));
+        if (hint)
+            print(hint);
     }
     catch {
         /* 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,42 @@ 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.
+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?1: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 +115,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/dist/telemetry.js

@@ -18,6 +18,7 @@ const PROJECT_KEYS = {
 };
 // The send is awaited before the process exits, so it gets one bounded attempt and no retry.
 const SEND_TIMEOUT_MS = 1500;
+const ID_FILE = join(os.homedir(), '.insta', 'telemetry.json');
 const REDACTED = '[REDACTED]';
 const oneOf = (values) => (v) => values.includes(v);
 const ID = (v) => /^(?:[0-9a-f]{8}-[0-9a-f-]{27}|[a-z]+_[\w-]{1,64}|(?=.*\d)[\w-]{1,64})$/i.test(v);
@@ -144,6 +145,7 @@ export function buildCommandEvent(command, args, options, outcome, ctx) {
             auth_kind: token ? (token.startsWith('insta_') ? 'api_key' : 'session') : null,
             project_id: ctx.project?.projectId ?? null,
             org_id: ctx.project?.orgId ?? null,
+            ...(ctx.project ? { $groups: { project: ctx.project.projectId, ...(ID(ctx.project.orgId) ? { org: ctx.project.orgId } : {}) } } : {}),
             tty: ctx.tty,
             ci: !!ctx.env.CI,
             agent: detectAgent(ctx.env),
@@ -154,20 +156,22 @@ export function buildCommandEvent(command, args, options, outcome, ctx) {
         },
     };
 }
-export async function anonymousId(file = join(os.homedir(), '.insta', 'telemetry.json')) {
+export async function readState(file = ID_FILE) {
     try {
         const parsed = JSON.parse(await readFile(file, 'utf8'));
         if (typeof parsed.anonymousId === 'string' && parsed.anonymousId)
-            return parsed.anonymousId;
+            return parsed;
     }
     catch { }
-    const id = randomUUID();
+    return writeState({ anonymousId: randomUUID() }, file);
+}
+async function writeState(state, file = ID_FILE) {
     try {
         await mkdir(dirname(file), { recursive: true });
-        await writeFile(file, JSON.stringify({ anonymousId: id }, null, 2));
+        await writeFile(file, JSON.stringify(state, null, 2));
     }
     catch { }
-    return id;
+    return state;
 }
 export async function sendBatch(key, batch, fetchImpl = fetch) {
     try {
@@ -201,16 +205,27 @@ export async function trackCommand(cmd, args, outcome, cliVersion, deps = {}) {
         if (!key)
             return;
         const project = await (deps.loadProject ?? readProject)();
+        const userId = config.user?.id;
+        let state = await readState(deps.idFile);
+        // Session gone or switched: the id belongs to the account that left, so later commands get a fresh one.
+        if (state.identifiedAs && state.identifiedAs !== userId)
+            state = await writeState({ anonymousId: randomUUID() }, deps.idFile);
         const event = buildCommandEvent(command, args.flat(), cmd.opts(), outcome, {
             cliVersion,
             channel: deps.channel ?? detectChannel(),
             config,
             project,
-            anonymousId: await anonymousId(deps.idFile),
+            anonymousId: state.anonymousId,
             env,
             tty: deps.tty ?? !!process.stdout.isTTY,
         });
-        await sendBatch(key, [event], deps.fetchImpl);
+        const batch = [event];
+        const merge = userId !== undefined && state.identifiedAs !== userId;
+        if (merge)
+            batch.push({ event: '$identify', distinct_id: userId, timestamp: event.timestamp, properties: { $anon_distinct_id: state.anonymousId } });
+        const sent = await sendBatch(key, batch, deps.fetchImpl);
+        if (merge && sent)
+            await writeState({ ...state, identifiedAs: userId }, deps.idFile);
     }
     catch { }
 }

package/package.json

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