@flowrail/init 0.0.9 → 0.0.11

package/dist/app-instance.js

@@ -0,0 +1,287 @@
+"use strict";
+/**
+ * ADR-019 M0' — durable app-instance identity (Decision 1).
+ *
+ * ``init`` mints an ``app_instance_id`` (mint-if-absent) into
+ * ``.flowrail/app.json`` and registers it with the server via the
+ * ``flowrail_register_app`` MCP tool. The identity is DURABLE:
+ *
+ *  - it lives in its own file, NOT ``context.json`` — the design-review
+ *    handoff file is rewritten by the skill on every review and carries
+ *    a 7-day staleness rule, both fatal for an identity that must
+ *    survive the life of the clone;
+ *  - an existing file is never re-minted or clobbered with a different
+ *    id (``writeAppIdentity`` throws rather than overwrite);
+ *  - registration is fail-soft — a dead network still yields a local
+ *    identity (``local_only``) and the next ``init`` re-registers it
+ *    idempotently.
+ *
+ * ``repo_key`` follows the hook's repo-scan convention EXACTLY
+ * (sha256 hex of the RAW remote string, first 16 chars; path fallback)
+ * so the lineage hint agrees across scan and registration events. The
+ * ``normalized_remote`` (canonical https form) exists only for the
+ * server-side rebind lookup — it is never hashed into ``repo_key``.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mintAppInstanceId = mintAppInstanceId;
+exports.normalizeRemoteUrl = normalizeRemoteUrl;
+exports.readAppIdentity = readAppIdentity;
+exports.writeAppIdentity = writeAppIdentity;
+exports.resolveRepoIdentity = resolveRepoIdentity;
+exports.ensureAppInstance = ensureAppInstance;
+const child_process_1 = require("child_process");
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const APP_JSON_DIR = '.flowrail';
+const APP_JSON_FILE = 'app.json';
+const REGISTER_TIMEOUT_MS = 10000;
+function mintAppInstanceId() {
+    return 'app_' + crypto_1.default.randomBytes(16).toString('hex');
+}
+/**
+ * Canonical https form of a git remote, used ONLY for the server-side
+ * rebind lookup. Handles scp-style ssh (``git@host:path``), ``ssh://``,
+ * and https (with embedded credentials stripped). Host is lowercased;
+ * path case is PRESERVED (GitHub owner/repo lookups are case-preserving
+ * even though resolution is case-insensitive).
+ */
+function normalizeRemoteUrl(raw) {
+    const trimmed = raw.trim();
+    let host;
+    let pathPart;
+    const scp = /^[A-Za-z0-9._-]+@([^:/]+):(.+)$/.exec(trimmed);
+    if (scp && !trimmed.includes('://')) {
+        host = scp[1];
+        pathPart = scp[2];
+    }
+    else {
+        const proto = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/(.+)$/.exec(trimmed);
+        let rest = proto ? proto[1] : trimmed;
+        // Strip credentials: anything before an ``@`` that precedes the
+        // first path slash belongs to userinfo, never the host.
+        const firstSlash = rest.indexOf('/');
+        const at = rest.indexOf('@');
+        if (at !== -1 && (firstSlash === -1 || at < firstSlash)) {
+            rest = rest.slice(at + 1);
+        }
+        const slash = rest.indexOf('/');
+        if (slash === -1) {
+            host = rest;
+            pathPart = '';
+        }
+        else {
+            host = rest.slice(0, slash);
+            pathPart = rest.slice(slash + 1);
+        }
+    }
+    pathPart = pathPart.replace(/\/+$/, '').replace(/\.git$/, '');
+    return `https://${host.toLowerCase()}${pathPart ? `/${pathPart}` : ''}`;
+}
+/** Read ``.flowrail/app.json``. Durable by design: NO staleness rule —
+ *  contrast the hook's context.json reader, which drops 7-day-old
+ *  contexts. Returns null on missing/malformed/typeless content. */
+function readAppIdentity(projectRoot) {
+    let raw;
+    try {
+        raw = fs_1.default.readFileSync(path_1.default.join(projectRoot, APP_JSON_DIR, APP_JSON_FILE), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return null;
+    }
+    const obj = parsed;
+    if (typeof obj['app_instance_id'] !== 'string')
+        return null;
+    return {
+        app_instance_id: obj['app_instance_id'],
+        created_at: typeof obj['created_at'] === 'string' ? obj['created_at'] : '',
+    };
+}
+/** Write ``.flowrail/app.json``. Never clobbers a DIFFERENT id — the
+ *  mint is permanent for the life of the clone (re-mint only via
+ *  delete/re-clone, per ADR-019 Decision 1). */
+function writeAppIdentity(projectRoot, identity) {
+    const existing = readAppIdentity(projectRoot);
+    if (existing !== null) {
+        if (existing.app_instance_id !== identity.app_instance_id) {
+            throw new Error(`.flowrail/app.json already holds app_instance_id ${existing.app_instance_id}; ` +
+                'refusing to overwrite a durable identity with a different one');
+        }
+        return; // idempotent: same id, keep the original file
+    }
+    const dir = path_1.default.join(projectRoot, APP_JSON_DIR);
+    fs_1.default.mkdirSync(dir, { recursive: true });
+    fs_1.default.writeFileSync(path_1.default.join(dir, APP_JSON_FILE), JSON.stringify(identity, null, 2) + '\n', 'utf8');
+}
+function defaultGitRemote(projectRoot) {
+    try {
+        const out = (0, child_process_1.execFileSync)('git', ['-C', projectRoot, 'config', '--get', 'remote.origin.url'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 1000 }).trim();
+        return out.length > 0 ? out : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function shortHash(value) {
+    return crypto_1.default.createHash('sha256').update(value).digest('hex').slice(0, 16);
+}
+/**
+ * Resolve the repo identity triple. ``repoKey`` hashes the RAW remote
+ * string (never the normalized form) to stay byte-identical with the
+ * hook's repo-scan ``resolveRepoKey`` — the two surfaces must agree or
+ * lineage grouping by repo_key silently forks.
+ */
+function resolveRepoIdentity(projectRoot, deps = {}) {
+    const gitRemote = deps.gitRemote ?? defaultGitRemote;
+    const raw = gitRemote(projectRoot);
+    if (raw !== undefined) {
+        return {
+            normalizedRemote: normalizeRemoteUrl(raw),
+            repoKey: shortHash(raw),
+            remotePresent: true,
+        };
+    }
+    return {
+        normalizedRemote: null,
+        repoKey: shortHash(path_1.default.resolve(projectRoot)),
+        remotePresent: false,
+    };
+}
+function buildDefaultRegisterApp(mcpBaseUrl, apiKey) {
+    const url = `${mcpBaseUrl.replace(/\/+$/, '')}/mcp`;
+    return async (args) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), REGISTER_TIMEOUT_MS);
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    authorization: `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: 1,
+                    method: 'tools/call',
+                    params: { name: 'flowrail_register_app', arguments: args },
+                }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                return { error: `HTTP ${response.status}` };
+            }
+            const body = (await response.json());
+            if (body.error) {
+                return { error: body.error.message ?? 'JSON-RPC error' };
+            }
+            const structured = body.result?.structuredContent;
+            if (structured &&
+                typeof structured['status'] === 'string' &&
+                typeof structured['app_instance_id'] === 'string') {
+                return structured;
+            }
+            return { error: 'malformed flowrail_register_app response' };
+        }
+        catch (err) {
+            return { error: err instanceof Error ? err.message : String(err) };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+}
+/**
+ * Mint-if-absent + register. Every path yields a durable local identity;
+ * only the registration round-trip is best-effort.
+ */
+async function ensureAppInstance(opts) {
+    const registerApp = opts.registerApp ?? buildDefaultRegisterApp(opts.mcpBaseUrl, opts.apiKey);
+    const repo = resolveRepoIdentity(opts.projectRoot);
+    const registerArgs = (appInstanceId, extra = {}) => {
+        const args = {
+            app_instance_id: appInstanceId,
+            repo_key: repo.repoKey,
+            remote_present: repo.remotePresent,
+            ...extra,
+        };
+        if (repo.normalizedRemote !== null) {
+            args['normalized_remote'] = repo.normalizedRemote;
+        }
+        return args;
+    };
+    const callRegister = async (args) => {
+        try {
+            return await registerApp(args);
+        }
+        catch (err) {
+            return { error: err instanceof Error ? err.message : String(err) };
+        }
+    };
+    const existing = readAppIdentity(opts.projectRoot);
+    if (existing !== null) {
+        // Idempotent re-register of the durable id. Any server-side outcome
+        // that acknowledges the id maps to 'ok'; failure is fail-soft.
+        const res = await callRegister(registerArgs(existing.app_instance_id));
+        if ('error' in res) {
+            opts.log(`FlowRail: app-instance registration deferred (${res.error}); ` +
+                'the local identity is kept and re-registered on the next init.');
+            return { appInstanceId: existing.app_instance_id, status: 'local_only' };
+        }
+        return { appInstanceId: existing.app_instance_id, status: 'ok' };
+    }
+    const minted = mintAppInstanceId();
+    const identity = {
+        app_instance_id: minted,
+        created_at: new Date().toISOString(),
+    };
+    const first = await callRegister(registerArgs(minted));
+    if ('error' in first) {
+        writeAppIdentity(opts.projectRoot, identity);
+        opts.log(`FlowRail: app-instance registration deferred (${first.error}); ` +
+            'minted a local identity — the next init re-registers it.');
+        return { appInstanceId: minted, status: 'local_only' };
+    }
+    if (first.status === 'existing') {
+        // The rebind offer: this remote is already registered under a
+        // different instance id (a prior clone).
+        if (opts.rebind) {
+            const adopted = {
+                app_instance_id: first.app_instance_id,
+                created_at: first.created_at ?? new Date().toISOString(),
+            };
+            writeAppIdentity(opts.projectRoot, adopted);
+            opts.log(`✓ rebound to existing app instance ${first.app_instance_id} for this remote`);
+            return {
+                appInstanceId: first.app_instance_id,
+                status: 'existing_adopted',
+            };
+        }
+        opts.log(`FlowRail: this remote is already registered as app instance ${first.app_instance_id}.`);
+        opts.log('  Minting a fresh instance for this clone (graphs are per-clone). To adopt the');
+        opts.log('  existing identity instead, re-run init with --rebind (or FLOWRAIL_APP_REBIND=1).');
+        const forced = await callRegister(registerArgs(minted, { force_new: true }));
+        writeAppIdentity(opts.projectRoot, identity);
+        if ('error' in forced) {
+            opts.log(`FlowRail: forced registration deferred (${forced.error}); ` +
+                'the local identity is kept and re-registered on the next init.');
+            return { appInstanceId: minted, status: 'local_only' };
+        }
+        return { appInstanceId: minted, status: 'forced_new' };
+    }
+    // 'registered' (or an unexpectedly-lenient 'ok') — persist the mint.
+    writeAppIdentity(opts.projectRoot, identity);
+    return { appInstanceId: minted, status: 'registered' };
+}

package/dist/claude-settings.js

@@ -3,15 +3,16 @@
  * Read / merge / write ``.claude/settings.json``.
  *
  * Wires PreToolUse hooks for Write/Edit/MultiEdit (pre-write
- * dispatcher) and Bash (pre-bash dispatcher). Both invoke
- * ``flowrail-hook`` from the @flowrail/hook package the tester is
- * expected to have installed alongside this init.
+ * dispatcher) and Bash (pre-bash dispatcher), plus the ADR-019 Stop
+ * (turn-batched whole-app review) and SessionStart (coverage catch-up)
+ * hooks. All invoke ``flowrail-hook`` from the @flowrail/hook package
+ * the tester is expected to have installed alongside this init.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PRE_BASH_MATCHER = exports.PRE_WRITE_MATCHER = void 0;
+exports.REVIEW_HOOK_TIMEOUT_SECONDS = exports.PRE_BASH_MATCHER = exports.PRE_WRITE_MATCHER = void 0;
 exports.buildHookCommand = buildHookCommand;
 exports.mergeClaudeSettings = mergeClaudeSettings;
 exports.writeClaudeSettings = writeClaudeSettings;
@@ -26,6 +27,12 @@ const HOOK_BIN_NAME = 'flowrail-hook';
 const HOOK_BIN = `npx --yes -p @flowrail/hook ${HOOK_BIN_NAME}`;
 exports.PRE_WRITE_MATCHER = 'Write|Edit|MultiEdit';
 exports.PRE_BASH_MATCHER = 'Bash';
+// ADR-019 failure posture: the Stop/SessionStart hook timeout is sized
+// to batched whole-app reality and set EXPLICITLY in the generated
+// settings entry (seconds). It sits above the hook's own HTTP client
+// timeout so the client, not Claude Code, decides how a slow review
+// degrades (fail-open with telemetry, never a killed process).
+exports.REVIEW_HOOK_TIMEOUT_SECONDS = 180;
 /**
  * Build the hook command for a sub-dispatcher. We MUST bake
  * ``FLOWRAIL_MCP_URL=<base>`` in front of the npx invocation —
@@ -51,6 +58,17 @@ function flowrailHookGroups(mcpBaseUrl) {
         },
     ];
 }
+function flowrailReviewGroup(subcommand, mcpBaseUrl) {
+    return {
+        hooks: [
+            {
+                type: 'command',
+                command: buildHookCommand(subcommand, mcpBaseUrl),
+                timeout: exports.REVIEW_HOOK_TIMEOUT_SECONDS,
+            },
+        ],
+    };
+}
 function isFlowrailGroup(group) {
     // Identify a group as "ours" if any inner hook command points at the
     // flowrail-hook binary, regardless of which sub-command. Conservative
@@ -58,16 +76,27 @@ function isFlowrailGroup(group) {
     // with two flowrail PreToolUse entries every time they re-run init.
     return group.hooks.some((h) => typeof h.command === 'string' && h.command.includes(HOOK_BIN_NAME));
 }
+function mergeGroups(existing, ours) {
+    // Drop any prior flowrail entries before re-inserting so re-running
+    // init is idempotent (no duplicate groups piling up); foreign groups
+    // are preserved verbatim.
+    const others = (existing ?? []).filter((g) => !isFlowrailGroup(g));
+    return [...others, ...ours];
+}
 function mergeClaudeSettings(existing, mcpBaseUrl) {
     const existingHooks = existing.hooks ?? {};
-    const existingPreToolUse = existingHooks.PreToolUse ?? [];
-    // Drop any prior flowrail PreToolUse entries before re-inserting so
-    // re-running init is idempotent (no duplicate matchers piling up).
-    const otherGroups = existingPreToolUse.filter((g) => !isFlowrailGroup(g));
-    const PreToolUse = [...otherGroups, ...flowrailHookGroups(mcpBaseUrl)];
     return {
         ...existing,
-        hooks: { ...existingHooks, PreToolUse },
+        hooks: {
+            ...existingHooks,
+            PreToolUse: mergeGroups(existingHooks.PreToolUse, flowrailHookGroups(mcpBaseUrl)),
+            Stop: mergeGroups(existingHooks.Stop, [
+                flowrailReviewGroup('stop', mcpBaseUrl),
+            ]),
+            SessionStart: mergeGroups(existingHooks.SessionStart, [
+                flowrailReviewGroup('session-start', mcpBaseUrl),
+            ]),
+        },
     };
 }
 function writeClaudeSettings(projectRoot, mcpBaseUrl) {