@flowrail/init 0.0.7

package/README.md

@@ -0,0 +1,27 @@
+# @flowrail/init
+
+One-shot installer that wires FlowRail's PreToolUse hooks, MCP server config, and skill markdown into a Claude Code project.
+
+```bash
+export FLOWRAIL_API_KEY=fs_poc_<slug>_<random>    # from your FlowRail operator
+cd ~/code/your-repo
+npx @flowrail/init
+```
+
+What it writes:
+
+- `.claude/settings.json` — PreToolUse hooks for Write/Edit/MultiEdit + Bash. Tracked. No credentials.
+- `.mcp.json` — Claude Code MCP wiring. Tracked. Carries `Bearer ${FLOWRAIL_API_KEY}` env-reference, never the literal.
+- `.claude/skills/flowrail-*/SKILL.md` — four agent-facing skills (design-review, verify, lineage, dep-check).
+- `flowrail.yaml` — placeholder project config; v1 hooks scanner orchestration + org defaults here.
+- `.gitignore` — appends `.flowrail/` so per-session runtime state (active design_review_id) stays local.
+
+The installer also probes `https://api.flowrail.ai/mcp` with the env-supplied bearer to confirm end-to-end auth before exiting. A 401 gets a tester-actionable message; transport failures get a different one.
+
+**Full install guide**: <https://github.com/anshumanbh/flowstate/blob/main/docs/INSTALL.md>
+
+**Troubleshooting**: <https://github.com/anshumanbh/flowstate/blob/main/docs/TROUBLESHOOTING.md>
+
+**Honest limits**: <https://github.com/anshumanbh/flowstate/blob/main/docs/LIMITS.md>
+
+This is a POC — eval-only, not for production. Source: <https://github.com/anshumanbh/flowstate>.

package/dist/claude-settings.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * 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.
+ */
+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.buildHookCommand = buildHookCommand;
+exports.mergeClaudeSettings = mergeClaudeSettings;
+exports.writeClaudeSettings = writeClaudeSettings;
+const path_1 = __importDefault(require("path"));
+const json_config_1 = require("./json-config");
+// Shared as a constant so the idempotency check below ("is this group
+// ours?") can derive its match marker from the same source — without
+// that, a renamed hook bin silently breaks re-run idempotency.
+const HOOK_BIN_NAME = 'flowrail-hook';
+// --yes skips the interactive install prompt so the hook works in fresh
+// worktrees (created by start_code_task) where node_modules may not exist.
+const HOOK_BIN = `npx --yes -p @flowrail/hook ${HOOK_BIN_NAME}`;
+exports.PRE_WRITE_MATCHER = 'Write|Edit|MultiEdit';
+exports.PRE_BASH_MATCHER = 'Bash';
+/**
+ * Build the hook command for a sub-dispatcher. We MUST bake
+ * ``FLOWRAIL_MCP_URL=<base>`` in front of the npx invocation —
+ * @flowrail/hook's ``resolveEndpoint`` reads that env var and falls
+ * back to ``http://localhost:8787``. Without the prefix, the hook
+ * silently calls localhost on every Write/Edit/Bash and every gate
+ * fails open — the install would probe api.flowrail.ai successfully
+ * and the runtime hooks would never reach it. Pinned by the
+ * "hook command embeds the install-time MCP base URL" tests.
+ */
+function buildHookCommand(subcommand, mcpBaseUrl) {
+    return `FLOWRAIL_MCP_URL=${mcpBaseUrl} ${HOOK_BIN} ${subcommand}`;
+}
+function flowrailHookGroups(mcpBaseUrl) {
+    return [
+        {
+            matcher: exports.PRE_WRITE_MATCHER,
+            hooks: [{ type: 'command', command: buildHookCommand('pre-write', mcpBaseUrl) }],
+        },
+        {
+            matcher: exports.PRE_BASH_MATCHER,
+            hooks: [{ type: 'command', command: buildHookCommand('pre-bash', mcpBaseUrl) }],
+        },
+    ];
+}
+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
+    // match so a tester who renames their shell wrapper doesn't end up
+    // 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 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 },
+    };
+}
+function writeClaudeSettings(projectRoot, mcpBaseUrl) {
+    (0, json_config_1.readMergeWriteJson)(path_1.default.join(projectRoot, '.claude', 'settings.json'), (existing) => mergeClaudeSettings(existing, mcpBaseUrl));
+}

package/dist/connectivity.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * Connectivity check against ``api.flowrail.ai/mcp``.
+ *
+ * Sends a single ``tools/list`` JSON-RPC call carrying the bearer.
+ * 200 + ``result.tools`` non-empty → pass. 401 → bearer is wrong.
+ * Any other shape is a transient error the tester should retry. The
+ * signal we actually care about: "the env-supplied bearer authenticates
+ * end-to-end, including DNS + TLS + Fly + auth + tool registry." If
+ * any rung fails the install is broken regardless of the file writes.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkConnectivity = checkConnectivity;
+const http_1 = __importDefault(require("http"));
+const https_1 = __importDefault(require("https"));
+const url_1 = require("url");
+const env_1 = require("./env");
+const mcp_config_1 = require("./mcp-config");
+// Hard wall-clock deadline for the whole probe — Node's per-request
+// ``timeout`` option only fires on socket inactivity, so a server that
+// drips one byte every few seconds during the response body would
+// otherwise hang the install indefinitely. 15s is generous against
+// real RTT to Fly + cold-start, tight enough to fail an obvious hang.
+const PROBE_DEADLINE_MS = 15000;
+const defaultFetcher = (url, init) => new Promise((resolve, reject) => {
+    const parsed = new url_1.URL(url);
+    // Pick the right module by scheme. Prod traffic is https; local
+    // dev / staging probes via FLOWRAIL_MCP_URL may be http.
+    const transport = parsed.protocol === 'http:' ? http_1.default : https_1.default;
+    let settled = false;
+    const settleReject = (err) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(deadline);
+        reject(err);
+    };
+    const settleResolve = (value) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(deadline);
+        resolve(value);
+    };
+    const req = transport.request({
+        method: init.method,
+        host: parsed.hostname,
+        port: parsed.port || undefined,
+        path: parsed.pathname + parsed.search,
+        headers: { ...init.headers, 'content-length': Buffer.byteLength(init.body) },
+        timeout: 10000,
+    }, (res) => {
+        const chunks = [];
+        res.on('data', (c) => chunks.push(c));
+        res.on('end', () => settleResolve({
+            status: res.statusCode ?? 0,
+            body: Buffer.concat(chunks).toString('utf8'),
+        }));
+        res.on('error', settleReject);
+    });
+    const deadline = setTimeout(() => {
+        req.destroy(new Error(`connectivity probe exceeded ${PROBE_DEADLINE_MS / 1000}s wall-clock deadline`));
+    }, PROBE_DEADLINE_MS);
+    req.on('error', settleReject);
+    req.on('timeout', () => {
+        req.destroy(new Error('connectivity probe socket idle for 10s'));
+    });
+    req.write(init.body);
+    req.end();
+});
+async function checkConnectivity(opts) {
+    const url = opts.url ?? (0, mcp_config_1.mcpUrlFromBase)(mcp_config_1.MCP_BASE_URL_DEFAULT);
+    const fetcher = opts.fetcher ?? defaultFetcher;
+    const body = JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/list',
+    });
+    let response;
+    try {
+        response = await fetcher(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${opts.apiKey}`,
+            },
+            body,
+        });
+    }
+    catch (err) {
+        throw new env_1.InitError(`Connectivity probe to ${url} failed: ${err.message}. ` +
+            `Check your network, that the URL is reachable, and that DNS for ` +
+            `api.flowrail.ai resolves.`);
+    }
+    if (response.status === 401) {
+        throw new env_1.InitError(`Connectivity probe got 401 from ${url}. The bearer in ` +
+            `$FLOWRAIL_API_KEY isn't recognized. Confirm the value with your ` +
+            `operator — most likely it was revoked or never registered.`);
+    }
+    if (response.status !== 200) {
+        throw new env_1.InitError(`Connectivity probe got HTTP ${response.status} from ${url}. ` +
+            `Server may be unhealthy; check https://api.flowrail.ai/health and retry.`);
+    }
+    // Confirm the response shape — a 200 with an unexpected body would
+    // pass the status check but mean the URL is pointing at the wrong
+    // server (e.g. a captive portal).
+    let parsed;
+    try {
+        parsed = JSON.parse(response.body);
+    }
+    catch {
+        throw new env_1.InitError(`Connectivity probe to ${url} returned non-JSON. The endpoint ` +
+            `may be a proxy or captive portal rather than the FlowRail server.`);
+    }
+    const tools = parsed.result?.tools;
+    if (!Array.isArray(tools) || tools.length === 0) {
+        throw new env_1.InitError(`Connectivity probe got a JSON-RPC response from ${url} but no ` +
+            `tools were registered. The server is likely misconfigured — ` +
+            `notify the operator.`);
+    }
+}

package/dist/doctor-script.js

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOCTOR_SCRIPT_FILENAME = void 0;
+exports.writeDoctorScript = writeDoctorScript;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+exports.DOCTOR_SCRIPT_FILENAME = 'scripts/check-flowrail.mjs';
+/**
+ * The content of the doctor script dropped into the target repo.
+ * It is a self-contained ES module — no deps outside node:fs.
+ */
+const DOCTOR_SCRIPT_CONTENT = `#!/usr/bin/env node
+/**
+ * FlowRail doctor script — checks that .mcp.json is present and wired.
+ * Generated by @flowrail/init. Safe to commit to the repo.
+ * Re-run the installer if this script fails: npx @flowrail/init@latest
+ */
+import { existsSync, readFileSync } from 'node:fs';
+
+const mcpPath = '.mcp.json';
+let ok = true;
+
+if (!existsSync(mcpPath)) {
+  console.error(
+    'FlowRail: .mcp.json is missing — Claude Code MCP tools ' +
+      '(mcp__flowrail__*) will not be available.\\n' +
+      'Fix: npx @flowrail/init@latest',
+  );
+  ok = false;
+} else {
+  try {
+    const cfg = JSON.parse(readFileSync(mcpPath, 'utf8'));
+    if (!cfg?.mcpServers?.flowrail) {
+      console.error(
+        'FlowRail: .mcp.json has no mcpServers.flowrail entry — ' +
+          'Claude Code MCP tools (mcp__flowrail__*) will not be available.\\n' +
+          'Fix: npx @flowrail/init@latest',
+      );
+      ok = false;
+    }
+  } catch {
+    console.error(
+      'FlowRail: .mcp.json is malformed JSON.\\n' +
+        'Fix: delete it and re-run: npx @flowrail/init@latest',
+    );
+    ok = false;
+  }
+}
+
+if (!ok) process.exit(1);
+`;
+/**
+ * Writes (or overwrites) the FlowRail doctor script into `scripts/` inside
+ * the target project. The script exits 1 when `.mcp.json` is absent or
+ * missing the `mcpServers.flowrail` entry. Wire it to `predev`/`prebuild`
+ * so contributors see the failure before their first dev-server start.
+ */
+function writeDoctorScript(projectRoot) {
+    const target = path_1.default.join(projectRoot, exports.DOCTOR_SCRIPT_FILENAME);
+    fs_1.default.mkdirSync(path_1.default.dirname(target), { recursive: true });
+    fs_1.default.writeFileSync(target, DOCTOR_SCRIPT_CONTENT, 'utf8');
+}

package/dist/env.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Env + argv validation for the FlowRail init CLI.
+ *
+ * The bearer token MUST come from $FLOWRAIL_API_KEY, never from argv.
+ * --key= would land the credential in shell history, ps output, and
+ * any other place the kernel exposes argv to other UIDs. Rejecting it
+ * up front and pointing the user at the env path keeps the installer
+ * one-shot and avoids documenting a foot-gun.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InitError = exports.API_KEY_PREFIX = exports.API_KEY_ENV = void 0;
+exports.rejectKeyArgv = rejectKeyArgv;
+exports.readApiKeyFromEnv = readApiKeyFromEnv;
+exports.API_KEY_ENV = 'FLOWRAIL_API_KEY';
+exports.API_KEY_PREFIX = 'fs_poc_';
+class InitError extends Error {
+    constructor() {
+        super(...arguments);
+        // Tag so the CLI entry point can distinguish "expected" config errors
+        // (print message, exit 2) from genuine bugs (print stack, exit 1).
+        this.kind = 'init-error';
+    }
+}
+exports.InitError = InitError;
+function rejectKeyArgv(argv) {
+    for (const arg of argv) {
+        // Match --key=, --key SPACE, --api-key=, etc. We don't need a
+        // permissive parser — any flag-shaped token mentioning "key" is
+        // worth rejecting because the credential never belongs in argv.
+        if (/^--?(api[-_]?)?key([=\s]|$)/i.test(arg)) {
+            throw new InitError(`${arg} is not a supported flag. Set the bearer in the ` +
+                `${exports.API_KEY_ENV} env var instead — argv is visible in shell ` +
+                `history and process listings.`);
+        }
+    }
+}
+function readApiKeyFromEnv(env) {
+    const raw = env[exports.API_KEY_ENV];
+    if (raw === undefined || raw === '') {
+        throw new InitError(`${exports.API_KEY_ENV} is not set. Export the bearer your operator emailed ` +
+            `you (e.g. \`export ${exports.API_KEY_ENV}=fs_poc_...\`) and re-run.`);
+    }
+    if (!raw.startsWith(exports.API_KEY_PREFIX)) {
+        throw new InitError(`${exports.API_KEY_ENV} doesn't look like a FlowRail API key (expected prefix ` +
+            `"${exports.API_KEY_PREFIX}"). Double-check the value the operator sent — ` +
+            `dashboard tokens (fs_dash_*) and scratch values won't authenticate ` +
+            `against the MCP surface.`);
+    }
+    // Reject any control / whitespace contamination — a stray \r\n from
+    // a copy-paste would otherwise become a header-injection vector when
+    // the connectivity probe puts the value into ``Authorization: Bearer``.
+    if (/[\s\x00-\x1f\x7f]/.test(raw)) {
+        throw new InitError(`${exports.API_KEY_ENV} contains whitespace or control characters. ` +
+            `Re-copy the value from the operator's email — most likely a ` +
+            `trailing newline slipped in.`);
+    }
+    return { apiKey: raw };
+}

package/dist/flowrail-yaml.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Write the project-level ``flowrail.yaml`` (POC.md §4.3 C1, SPEC.md §4.5.1).
+ *
+ * The committed config is the future hook for tester-side scanner
+ * orchestration + allowlist overrides (SPEC.md §4.5.1 §3 — version,
+ * org, scanners[]). For the POC scope none of those layers are wired
+ * server-side yet, so the shipped contents are a ``version: 1`` stub
+ * with explanatory comments. The file existing at all is what
+ * downstream features (B+/v1 scanners, org-default inheritance) need —
+ * the contents themselves can stay minimal until those land.
+ *
+ * Idempotent: if the tester has already customised the file, leave it
+ * alone. Clobbering would silently destroy a hand-curated allowlist.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FLOWRAIL_YAML_FILENAME = void 0;
+exports.writeFlowrailYaml = writeFlowrailYaml;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+exports.FLOWRAIL_YAML_FILENAME = 'flowrail.yaml';
+const DEFAULT_FLOWRAIL_YAML = `# FlowRail project config (POC). Committed to the repo so every
+# clone of this project picks up the same gating shape.
+#
+# For the POC, this file is a placeholder — the hook + MCP server
+# enforce a fixed set of guardrails today, with no per-repo tuning
+# beyond the design-review-derived allowlist. v1 wires this file to:
+#
+#   * scanner orchestration (run semgrep / trufflehog / bandit /
+#     custom commands and feed verdicts back to the verifier)
+#   * org-wide guardrail defaults via "org: <name>"
+#   * per-repo overrides on the design-review approved-deps list
+#
+# Until then, leave this as-is or add an "org:" line if your operator
+# pointed you at one.
+version: 1
+`;
+function writeFlowrailYaml(projectRoot) {
+    const target = path_1.default.join(projectRoot, exports.FLOWRAIL_YAML_FILENAME);
+    if (fs_1.default.existsSync(target)) {
+        // Don't clobber a hand-edited file. The init's job is one-shot
+        // bootstrap; ongoing curation belongs to the tester.
+        return;
+    }
+    fs_1.default.writeFileSync(target, DEFAULT_FLOWRAIL_YAML, 'utf8');
+}

package/dist/git-check.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMcpJsonGitTracked = isMcpJsonGitTracked;
+const child_process_1 = require("child_process");
+/**
+ * Returns true if `.mcp.json` is currently tracked by git in the given
+ * project root. Returns false if the file is untracked, gitignored, the
+ * directory is not a git repo, or git is not available on PATH.
+ */
+function isMcpJsonGitTracked(projectRoot) {
+    const result = (0, child_process_1.spawnSync)('git', ['ls-files', '--error-unmatch', '.mcp.json'], {
+        cwd: projectRoot,
+        stdio: 'pipe',
+        encoding: 'utf8',
+    });
+    return result.status === 0;
+}

package/dist/gitignore.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Append gitignore entries idempotently.
+ *
+ * `.flowrail/` — per-tester runtime state; local-only, never committed.
+ * `.mcp.json`  — per-contributor MCP config; also local-only. Including
+ *                 a regeneration comment inline in `.gitignore` surfaces
+ *                 the `npx @flowrail/init@latest` fix command to
+ *                 anyone who hits the "silent missing MCP" trap (issue #113).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP_JSON_GITIGNORE_COMMENT = exports.MCP_JSON_GITIGNORE_ENTRY = exports.FLOWRAIL_GITIGNORE_ENTRY = void 0;
+exports.appendFlowrailToGitignore = appendFlowrailToGitignore;
+exports.appendMcpJsonToGitignore = appendMcpJsonToGitignore;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+exports.FLOWRAIL_GITIGNORE_ENTRY = '.flowrail/';
+exports.MCP_JSON_GITIGNORE_ENTRY = '.mcp.json';
+/**
+ * Appended above the `.mcp.json` line so any contributor reading
+ * `.gitignore` (or diffing `f246a8c`-style untrack commits) sees how
+ * to regenerate the file without hunting docs.
+ */
+exports.MCP_JSON_GITIGNORE_COMMENT = '# Per-contributor MCP config — regenerate with: npx @flowrail/init@latest';
+function appendFlowrailToGitignore(projectRoot) {
+    const target = path_1.default.join(projectRoot, '.gitignore');
+    let body = '';
+    if (fs_1.default.existsSync(target)) {
+        body = fs_1.default.readFileSync(target, 'utf8');
+        // Already present (with or without a trailing slash) — nothing
+        // to do. Match line-anchored so a user-supplied negation like
+        // ``!.flowrail/keep`` doesn't trick us.
+        const pattern = /^\s*\.flowrail\/?\s*$/m;
+        if (pattern.test(body)) {
+            return;
+        }
+    }
+    const prefix = body.length === 0 || body.endsWith('\n') ? '' : '\n';
+    const block = `${prefix}# FlowRail per-tester runtime state (active design_review_id, etc).\n` +
+        `${exports.FLOWRAIL_GITIGNORE_ENTRY}\n`;
+    fs_1.default.writeFileSync(target, body + block, 'utf8');
+}
+/**
+ * Append `.mcp.json` to `.gitignore` with a regeneration comment above it.
+ * Idempotent: no-ops if `.mcp.json` is already present on its own line
+ * (with or without a leading comment).
+ */
+function appendMcpJsonToGitignore(projectRoot) {
+    const target = path_1.default.join(projectRoot, '.gitignore');
+    let body = '';
+    if (fs_1.default.existsSync(target)) {
+        body = fs_1.default.readFileSync(target, 'utf8');
+        if (/^\s*\.mcp\.json\s*$/m.test(body)) {
+            return;
+        }
+    }
+    const prefix = body.length === 0 || body.endsWith('\n') ? '' : '\n';
+    const block = `${prefix}${exports.MCP_JSON_GITIGNORE_COMMENT}\n${exports.MCP_JSON_GITIGNORE_ENTRY}\n`;
+    fs_1.default.writeFileSync(target, body + block, 'utf8');
+}

package/dist/hook-install.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Install @flowrail/hook into the tester's project and verify
+ * the binary is runnable before declaring success.
+ *
+ * The runtime hook commands use `npx --yes -p @flowrail/hook` so they
+ * auto-install in fresh worktrees (e.g. start_code_task). This install
+ * step is still valuable: it records the dependency in devDependencies,
+ * ensures a working binary on the original checkout (no first-run
+ * latency), and catches broken packages at setup time with a clear error
+ * rather than a silent hook miss during a Write/Edit.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOOK_BIN = exports.HOOK_PACKAGE = void 0;
+exports.buildVerifyNodeScript = buildVerifyNodeScript;
+exports.installAndVerifyHook = installAndVerifyHook;
+const child_process_1 = require("child_process");
+const env_1 = require("./env");
+exports.HOOK_PACKAGE = '@flowrail/hook';
+exports.HOOK_BIN = 'flowrail-hook';
+const INSTALL_NPM_ARGS = ['install', '--save-dev', exports.HOOK_PACKAGE];
+/**
+ * The runtime hook command is `npx --yes -p @flowrail/hook flowrail-hook
+ * pre-{write,bash}` (see ``buildHookCommand`` in claude-settings.ts).
+ * The binary itself only accepts those two subcommands and exits 2 on
+ * anything else — so we cannot probe it with `--version`. Instead the
+ * verifier:
+ *
+ *   1. Resolves `@flowrail/hook/package.json` from the project root —
+ *      proves npm install populated node_modules.
+ *   2. Reads `pkg.bin[HOOK_BIN]` and requires object-form. String-form
+ *      `bin` on a scoped package derives the binary name from the
+ *      package name (so `@flowrail/hook` with `"bin": "x.js"` would
+ *      install as `hook`, NOT `flowrail-hook`) — accepting that would
+ *      be a false positive.
+ *   3. Spawns the bin file via `node` with no args. The hook entry
+ *      point writes `flowrail-hook: unknown subcommand ...` to stderr
+ *      and exits 2 when invoked without `pre-write`/`pre-bash`. We
+ *      require both signals. This proves the file is parseable, all
+ *      imports resolve at runtime, and the entry-point code runs to
+ *      completion — catching broken shims, syntax errors, missing
+ *      runtime deps, or a wrong binary masquerading at the bin path.
+ */
+function buildVerifyNodeScript(pkg, bin) {
+    const pkgJson = JSON.stringify(`${pkg}/package.json`);
+    const binName = JSON.stringify(bin);
+    return [
+        "const path = require('path');",
+        "const cp = require('child_process');",
+        `const pkgPath = require.resolve(${pkgJson}, { paths: [process.cwd()] });`,
+        'const pkg = require(pkgPath);',
+        `const binEntry = pkg.bin && typeof pkg.bin === 'object' ? pkg.bin[${binName}] : null;`,
+        `if (!binEntry) {`,
+        `  console.error('package.json bin must be an object with a ' + ${binName} + ' entry');`,
+        '  process.exit(2);',
+        '}',
+        'const binPath = path.resolve(path.dirname(pkgPath), binEntry);',
+        "const result = cp.spawnSync(process.execPath, [binPath], { encoding: 'utf8' });",
+        `if (result.status !== 2 || !/unknown subcommand/.test(result.stderr || '') || !new RegExp(${binName}).test(result.stderr || '')) {`,
+        "  console.error('binary self-test failed: status=' + result.status + ' stderr=' + (result.stderr || '').slice(0, 300));",
+        '  process.exit(2);',
+        '}',
+        "process.stdout.write(pkg.version || '');",
+    ].join('');
+}
+const VERIFY_NODE_ARGS = ['-e', buildVerifyNodeScript(exports.HOOK_PACKAGE, exports.HOOK_BIN)];
+const defaultExec = (file, args, options) => (0, child_process_1.execFileSync)(file, args, {
+    cwd: options.cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+})
+    .toString()
+    .trim();
+/**
+ * Installs @flowrail/hook as a devDependency and verifies the binary
+ * is runnable. Throws InitError with an actionable message on failure.
+ *
+ * The `exec` parameter is a test seam — production callers omit it.
+ */
+function installAndVerifyHook(projectRoot, exec = defaultExec) {
+    let installOutput;
+    try {
+        installOutput = exec('npm', INSTALL_NPM_ARGS, { cwd: projectRoot });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new env_1.InitError(`failed to install ${exports.HOOK_PACKAGE}: ${detail}\n` +
+            `Ensure npm is available and your project has a package.json.`);
+    }
+    let version;
+    try {
+        version = exec('node', VERIFY_NODE_ARGS, { cwd: projectRoot });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new env_1.InitError(`${exports.HOOK_PACKAGE} was installed but its "${exports.HOOK_BIN}" binary could not be resolved: ${detail}\n` +
+            `Check that node_modules/${exports.HOOK_PACKAGE}/ exists and its package.json "bin" entry points at a real file.`);
+    }
+    return { installOutput, version };
+}

package/dist/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * @flowrail/init — one-shot installer for FlowRail POC.
+ * See ``init.ts`` for the orchestrator.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const env_1 = require("./env");
+const init_1 = require("./init");
+(0, init_1.runInit)().catch((err) => {
+    if (err instanceof env_1.InitError) {
+        // Expected configuration errors get a clean message + exit 2.
+        process.stderr.write(`flowrail-init: ${err.message}\n`);
+        process.exit(2);
+    }
+    // Anything else is a genuine bug — keep the stack so we can debug it.
+    const message = err instanceof Error ? err.stack ?? err.message : String(err);
+    process.stderr.write(`flowrail-init: unexpected error\n${message}\n`);
+    process.exit(1);
+});

package/dist/init.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * @flowrail/init — one-shot installer (POC.md §4.3 C1).
+ *
+ * Order of operations matters:
+ *
+ * 1. ``rejectKeyArgv`` first so a ``--key=`` invocation never even
+ *    reaches the env / write stages — bails out before any side effect.
+ * 2. ``readApiKeyFromEnv`` second so a missing/wrong-prefix bearer
+ *    surfaces before we touch the filesystem.
+ * 3. ``preflightNoLiteralTokens`` third — refuses to clobber a tracked
+ *    config that already has a real credential baked in (operator
+ *    error from a prior tool / hand-edit).
+ * 4. File writes (settings.json, .mcp.json, .gitignore, skills) happen
+ *    in dependency order: skill files come from a known-good source,
+ *    then claude settings reference them, then mcp config references
+ *    the env var, then .gitignore catches the runtime-state directory.
+ * 5. ``installAndVerifyHook`` installs and verifies the @flowrail/hook
+ *    binary locally. The runtime hook commands use `npx --yes` so they
+ *    auto-install in fresh worktrees, but the install step here catches
+ *    broken packages at setup time and records it in devDependencies.
+ *    Runs after file writes so config is consistent even if npm is slow;
+ *    errors here abort before the success message.
+ * 6. ``checkConnectivity`` last so the success message accurately says
+ *    "your laptop reached our server with this bearer." A failure here
+ *    leaves the config files in place — the tester can fix the network
+ *    and the install is already complete on their side.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInit = runInit;
+const claude_settings_1 = require("./claude-settings");
+const connectivity_1 = require("./connectivity");
+const doctor_script_1 = require("./doctor-script");
+const env_1 = require("./env");
+const flowrail_yaml_1 = require("./flowrail-yaml");
+const gitignore_1 = require("./gitignore");
+const git_check_1 = require("./git-check");
+const hook_install_1 = require("./hook-install");
+const mcp_config_1 = require("./mcp-config");
+const npm_hooks_1 = require("./npm-hooks");
+const preflight_1 = require("./preflight");
+const skills_1 = require("./skills");
+const verify_write_1 = require("./verify-write");
+async function runInit(options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const argv = options.argv ?? process.argv.slice(2);
+    const env = options.env ?? process.env;
+    const log = options.log ?? ((line) => process.stdout.write(line + '\n'));
+    const gitChecker = options.gitChecker ?? git_check_1.isMcpJsonGitTracked;
+    (0, env_1.rejectKeyArgv)(argv);
+    const { apiKey } = (0, env_1.readApiKeyFromEnv)(env);
+    // ``FLOWRAIL_MCP_URL`` is the BASE URL — same shape @flowrail/hook
+    // reads at runtime. Default to the prod base; staging / local-dev
+    // overrides set the env var before running init. The base flows into
+    // (a) the connectivity probe, (b) the .mcp.json url field, (c) the
+    // FLOWRAIL_MCP_URL=<base> env prefix on the hook command lines so
+    // the hooks call the same server the install probed against.
+    const mcpBaseUrl = env['FLOWRAIL_MCP_URL'] ?? mcp_config_1.MCP_BASE_URL_DEFAULT;
+    const connectivityUrl = options.connectivityUrl ?? (0, mcp_config_1.mcpUrlFromBase)(mcpBaseUrl);
+    (0, preflight_1.preflightNoLiteralTokens)(projectRoot);
+    const skillsSourceDir = options.skillsSourceDir ?? (0, skills_1.defaultSkillsSourceDir)();
+    const copyOpts = { projectRoot, skillsSourceDir };
+    (0, skills_1.copySkills)(copyOpts);
+    log(`✓ wrote ${skills_1.FLOWRAIL_SKILLS.length} skill(s) to .claude/skills/`);
+    (0, claude_settings_1.writeClaudeSettings)(projectRoot, mcpBaseUrl);
+    log('✓ wrote .claude/settings.json');
+    log(`    Write/Edit/MultiEdit → ${(0, claude_settings_1.buildHookCommand)('pre-write', mcpBaseUrl)}`);
+    log(`    Bash                 → ${(0, claude_settings_1.buildHookCommand)('pre-bash', mcpBaseUrl)}`);
+    (0, mcp_config_1.writeMcpConfig)(projectRoot, mcpBaseUrl);
+    log(`✓ wrote .mcp.json (mcpServers.flowrail → ${(0, mcp_config_1.mcpUrlFromBase)(mcpBaseUrl)}, ${mcp_config_1.MCP_AUTH_REFERENCE})`);
+    if (gitChecker(projectRoot)) {
+        log('⚠ .mcp.json is currently tracked by git. Contributors who pull a commit');
+        log('  that removes it (e.g. "untrack dev artifacts") will silently lose MCP');
+        log('  tools. Untrack it now:');
+        log('    git rm --cached .mcp.json && git commit -m "chore: untrack per-contributor .mcp.json"');
+    }
+    (0, flowrail_yaml_1.writeFlowrailYaml)(projectRoot);
+    log('✓ wrote flowrail.yaml');
+    (0, gitignore_1.appendFlowrailToGitignore)(projectRoot);
+    log('✓ ensured .flowrail/ is in .gitignore');
+    (0, gitignore_1.appendMcpJsonToGitignore)(projectRoot);
+    log('✓ ensured .mcp.json is in .gitignore (with regeneration comment)');
+    (0, doctor_script_1.writeDoctorScript)(projectRoot);
+    log('✓ wrote scripts/check-flowrail.mjs (doctor script)');
+    const npmPatched = (0, npm_hooks_1.patchNpmScripts)(projectRoot);
+    if (npmPatched) {
+        log('✓ wired FlowRail doctor into predev/prebuild npm scripts');
+    }
+    log(`→ installing ${hook_install_1.HOOK_PACKAGE}…`);
+    const hookResult = options.hookInstaller != null
+        ? options.hookInstaller()
+        : (0, hook_install_1.installAndVerifyHook)(projectRoot);
+    log(`✓ installed @flowrail/hook ${hookResult.version} (hook binary verified)`);
+    // Self-test: prove the installed hook actually *fires* on a write, not
+    // just that the binary resolves. Runs before the connectivity probe so
+    // the more fundamental "is FlowRail guarding writes at all?" failure
+    // surfaces first. A failure here throws InitError and aborts the
+    // install — a silent FlowRail is worse than a loud failure (issue #133).
+    log('→ self-testing the hook (a known test secret must be blocked)…');
+    const runSelfTest = options.hookSelfTest ??
+        (() => (0, verify_write_1.runHookSelfTest)({
+            resolveHookBinPath: () => (0, verify_write_1.resolveInstalledHookBinPath)(projectRoot),
+            runHook: verify_write_1.spawnHookPreWrite,
+            env,
+        }));
+    runSelfTest();
+    log('✓ hook self-test passed — write carrying a test secret was blocked');
+    log(`→ checking connectivity to ${connectivityUrl}…`);
+    await (0, connectivity_1.checkConnectivity)({
+        apiKey,
+        url: connectivityUrl,
+        fetcher: options.connectivityFetcher,
+    });
+    log('✓ connectivity check passed');
+    log('');
+    log('FlowRail is installed. Open this repo in Claude Code and start coding —');
+    log('design-review, verify, and dep-check skills are wired into the agent.');
+}

package/dist/json-config.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Shared "read existing JSON, merge, write back" helper used by
+ * ``mcp-config`` and ``claude-settings``. Both files do the same
+ * three-step dance with the same error message on malformed input,
+ * so consolidating here means the two writers can't drift on what
+ * "malformed" means or how to surface it.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readMergeWriteJson = readMergeWriteJson;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function readMergeWriteJson(target, merge) {
+    let existing = {};
+    if (fs_1.default.existsSync(target)) {
+        const raw = fs_1.default.readFileSync(target, 'utf8');
+        try {
+            existing = JSON.parse(raw);
+        }
+        catch {
+            // Malformed input is the operator's problem; refuse to clobber
+            // silently so the caller-provided merge logic can't accidentally
+            // overwrite the only copy of a hand-edited config.
+            throw new Error(`${target} is not valid JSON. Fix it or delete it before re-running.`);
+        }
+    }
+    else {
+        // Create the parent dir lazily so callers don't have to think
+        // about whether ``.claude/`` exists.
+        fs_1.default.mkdirSync(path_1.default.dirname(target), { recursive: true });
+    }
+    const merged = merge(existing);
+    fs_1.default.writeFileSync(target, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+}

package/dist/mcp-config.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Read / merge / write ``.mcp.json``.
+ *
+ * The tracked file holds the ``${FLOWRAIL_API_KEY}`` env-reference, NOT
+ * the resolved literal — without that distinction every committed
+ * .mcp.json would be a credential dump. Claude Code resolves the
+ * reference at runtime from the user's shell env.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP_AUTH_REFERENCE = exports.MCP_PATH = exports.MCP_BASE_URL_DEFAULT = exports.MCP_SERVER_NAME = void 0;
+exports.mcpUrlFromBase = mcpUrlFromBase;
+exports.flowrailMcpEntry = flowrailMcpEntry;
+exports.mergeMcpConfig = mergeMcpConfig;
+exports.writeMcpConfig = writeMcpConfig;
+const path_1 = __importDefault(require("path"));
+const env_1 = require("./env");
+const json_config_1 = require("./json-config");
+exports.MCP_SERVER_NAME = 'flowrail';
+// Base URL — the form ``@flowrail/hook`` reads from
+// ``FLOWRAIL_MCP_URL`` (it appends ``/mcp`` itself). Init writes this
+// onto the hook command line as an env prefix and also uses it as the
+// source of truth for ``.mcp.json`` + the connectivity probe.
+exports.MCP_BASE_URL_DEFAULT = 'https://api.flowrail.ai';
+exports.MCP_PATH = '/mcp';
+exports.MCP_AUTH_REFERENCE = `Bearer \${${env_1.API_KEY_ENV}}`;
+function mcpUrlFromBase(base) {
+    // Strip a trailing slash so an operator pasting "https://host/" gets
+    // a clean "https://host/mcp" rather than "https://host//mcp".
+    return `${base.replace(/\/+$/, '')}${exports.MCP_PATH}`;
+}
+function flowrailMcpEntry(baseUrl) {
+    return {
+        type: 'http',
+        url: mcpUrlFromBase(baseUrl),
+        headers: { Authorization: exports.MCP_AUTH_REFERENCE },
+    };
+}
+function mergeMcpConfig(existing, baseUrl) {
+    // Preserve any pre-existing mcpServers entries (the tester might
+    // already have other MCP servers wired). Overwrite ours specifically
+    // so a stale URL or header reference gets refreshed without
+    // surprising the user with duplicate keys.
+    const servers = { ...(existing.mcpServers ?? {}) };
+    servers[exports.MCP_SERVER_NAME] = flowrailMcpEntry(baseUrl);
+    return { ...existing, mcpServers: servers };
+}
+function writeMcpConfig(projectRoot, baseUrl) {
+    (0, json_config_1.readMergeWriteJson)(path_1.default.join(projectRoot, '.mcp.json'), (existing) => mergeMcpConfig(existing, baseUrl));
+}

package/dist/npm-hooks.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.patchNpmScripts = patchNpmScripts;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const doctor_script_1 = require("./doctor-script");
+const DOCTOR_COMMAND = `node ${doctor_script_1.DOCTOR_SCRIPT_FILENAME}`;
+const HOOKS_TO_PATCH = ['predev', 'prebuild'];
+/**
+ * Appends the FlowRail doctor command to `predev` and `prebuild` npm
+ * lifecycle scripts in the target repo's `package.json`. If either hook
+ * already exists the doctor command is appended with `&&`; if it doesn't
+ * exist a new entry is created. No-ops when there is no `package.json`,
+ * when `package.json` is malformed, or when the command is already present.
+ *
+ * Returns true when at least one script was modified and the file was
+ * rewritten, false otherwise.
+ */
+function patchNpmScripts(projectRoot) {
+    const pkgPath = path_1.default.join(projectRoot, 'package.json');
+    if (!fs_1.default.existsSync(pkgPath))
+        return false;
+    let pkg;
+    try {
+        pkg = JSON.parse(fs_1.default.readFileSync(pkgPath, 'utf8'));
+    }
+    catch {
+        return false;
+    }
+    const scripts = (typeof pkg.scripts === 'object' && pkg.scripts !== null
+        ? pkg.scripts
+        : {});
+    let changed = false;
+    for (const hook of HOOKS_TO_PATCH) {
+        const existing = scripts[hook];
+        if (existing === undefined) {
+            scripts[hook] = DOCTOR_COMMAND;
+            changed = true;
+        }
+        else if (!existing.includes(doctor_script_1.DOCTOR_SCRIPT_FILENAME)) {
+            scripts[hook] = `${existing} && ${DOCTOR_COMMAND}`;
+            changed = true;
+        }
+    }
+    if (changed) {
+        pkg.scripts = scripts;
+        fs_1.default.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+    }
+    return changed;
+}

package/dist/preflight.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Preflight: refuse to proceed if any tracked Claude Code config
+ * already contains a literal ``fs_poc_*`` token.
+ *
+ * The ``${FLOWRAIL_API_KEY}`` env-reference is the contract. A literal
+ * in ``.claude/settings.json`` / ``.mcp.json`` / ``.claude/settings.local.json``
+ * means the operator (or a previous tool) baked a real credential
+ * into a tracked file — exactly the failure mode the env-reference
+ * design exists to prevent. Catch it before init writes anything else.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.preflightNoLiteralTokens = preflightNoLiteralTokens;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const env_1 = require("./env");
+const env_2 = require("./env");
+const TRACKED_CONFIGS = [
+    '.claude/settings.json',
+    '.mcp.json',
+    '.claude/settings.local.json',
+];
+// Match ``fs_poc_<slug>_<random>`` literals — slug is alnum+dash+
+// underscore, suffix is hex-shaped. Loose enough to catch any plausible
+// real key; strict enough to skip the literal "fs_poc_" string in our
+// own documentation / comments.
+const LITERAL_TOKEN_RE = /fs_poc_[A-Za-z0-9_-]{1,40}_[A-Fa-f0-9]{8,}/;
+function preflightNoLiteralTokens(projectRoot) {
+    const offenders = [];
+    for (const rel of TRACKED_CONFIGS) {
+        const absolute = path_1.default.join(projectRoot, rel);
+        if (!fs_1.default.existsSync(absolute))
+            continue;
+        const body = fs_1.default.readFileSync(absolute, 'utf8');
+        if (LITERAL_TOKEN_RE.test(body)) {
+            offenders.push(rel);
+        }
+    }
+    if (offenders.length > 0) {
+        throw new env_2.InitError(`Refusing to proceed: literal "${env_1.API_KEY_PREFIX}*" token found in ` +
+            `tracked config: ${offenders.join(', ')}. Remove the literal — ` +
+            `the bearer must live in $FLOWRAIL_API_KEY and the config file ` +
+            `holds only the \${FLOWRAIL_API_KEY} reference.`);
+    }
+}

package/dist/skills.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Copy skill markdown into ``.claude/skills/``.
+ *
+ * The four skills (design-review, verify, lineage, dep-check) live in
+ * ``packages/skills/`` as the canonical source. The init copies them
+ * under the tester's ``.claude/skills/`` so Claude Code can resolve
+ * them locally — no runtime fetch, no wiggle between server and client.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FLOWRAIL_SKILLS = void 0;
+exports.copySkills = copySkills;
+exports.defaultSkillsSourceDir = defaultSkillsSourceDir;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+// Single source of truth for the four shipped skill names. Lives in
+// ``@flowrail/skills/manifest.json`` so the init copier and the
+// skills package's own integrity tests can't drift on which skills
+// are required.
+const manifest = require('@flowrail/skills/manifest.json');
+exports.FLOWRAIL_SKILLS = manifest.skills;
+function copySkills(opts) {
+    const targetRoot = path_1.default.join(opts.projectRoot, '.claude', 'skills');
+    fs_1.default.mkdirSync(targetRoot, { recursive: true });
+    for (const skill of exports.FLOWRAIL_SKILLS) {
+        const src = path_1.default.join(opts.skillsSourceDir, skill, 'SKILL.md');
+        if (!fs_1.default.existsSync(src)) {
+            // Fail loud — a missing skill at install time is a packaging bug,
+            // not a tester problem. Without this check, the agent would
+            // silently never invoke the missing skill and we'd debug it via
+            // a tester report instead of at install.
+            throw new Error(`expected SKILL.md at ${src} (workspace skills source missing)`);
+        }
+        const dstDir = path_1.default.join(targetRoot, skill);
+        fs_1.default.mkdirSync(dstDir, { recursive: true });
+        fs_1.default.copyFileSync(src, path_1.default.join(dstDir, 'SKILL.md'));
+    }
+}
+/**
+ * Default skills source — the sibling ``packages/skills/`` in the
+ * monorepo. ``require.resolve`` walks the resolution graph so it works
+ * even when the init package is symlinked into a tester's repo via
+ * ``npm link``.
+ */
+function defaultSkillsSourceDir() {
+    // The skills package's own ``package.json`` is the resolution
+    // anchor. Take its dirname to land on the package root.
+    const pkgJson = require.resolve('@flowrail/skills/package.json');
+    return path_1.default.dirname(pkgJson);
+}

package/dist/verify-write.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * Post-install hook self-test (issue #133).
+ *
+ * Connectivity (``connectivity.ts``) proves the laptop can reach the MCP
+ * server with this bearer. It does NOT prove the locally-installed hook
+ * actually *fires* on a write — a broken shim, a mis-wired
+ * ``.claude/settings.json``, or a hook that silently fails open would all
+ * pass connectivity while leaving the developer completely unguarded.
+ * That is the exact silent-failure this self-test closes: it drives the
+ * real installed ``flowrail-hook pre-write`` with a synthetic Write whose
+ * content carries a known test secret, and asserts the hook hard-denies.
+ *
+ * No file is written to disk — the Write payload carries the content
+ * inline and the hook reconstructs it from the payload, so the probe
+ * secret never lands on the filesystem and there is nothing to clean up.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnHookPreWrite = exports.PROBE_PATH = exports.PROBE_SECRET = void 0;
+exports.buildProbePayload = buildProbePayload;
+exports.runHookSelfTest = runHookSelfTest;
+exports.resolveInstalledHookBinPath = resolveInstalledHookBinPath;
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const env_1 = require("./env");
+const hook_install_1 = require("./hook-install");
+// AWS's published example access key (a well-known non-credential).
+// Assembled from fragments so the 20-char literal never appears verbatim
+// in this source file — otherwise FlowRail's own secret net (and any
+// other scanner) would flag this very file. At runtime the fragments
+// join into the full AKIA… string that the hook's ``/AKIA[0-9A-Z]{16}/``
+// net matches when it scans the probe payload.
+exports.PROBE_SECRET = ['AKIA', 'IOSFODNN7', 'EXAMPLE'].join('');
+// A plain, non-allowlisted, non-spec path so the hook's secret net runs:
+// paths under docs/ tests/ fixtures/ and ``*.spec.md`` short-circuit the
+// pipeline. The file is never created (see module docstring).
+exports.PROBE_PATH = 'flowrail-install-selftest.ts';
+/** Build the synthetic PreToolUse stdin the hook expects for a Write. */
+function buildProbePayload() {
+    return JSON.stringify({
+        tool_name: 'Write',
+        tool_input: {
+            file_path: exports.PROBE_PATH,
+            content: `const awsKey = "${exports.PROBE_SECRET}";\n`,
+        },
+    });
+}
+/**
+ * Drive the installed hook against the probe and throw ``InitError`` if it
+ * does not hard-deny. A non-firing guardrail is treated as an install
+ * failure: a silent FlowRail is worse than a loud failure (issue #133).
+ */
+function runHookSelfTest(deps) {
+    const binPath = deps.resolveHookBinPath();
+    // Point the spawned hook's telemetry at an unroutable loopback so its
+    // fire-and-forget secret_detected POST refuses instantly (fail-open)
+    // instead of writing a fake-secret event into the tester's real
+    // dashboard. The hard-deny under test is purely local and unaffected.
+    //
+    // FLOWRAIL_API_KEY must stay non-empty: the hook's env guard fails
+    // OPEN (exit 0, allow) when the key is absent, *before* the secret net
+    // runs — which would make a keyless run look like a self-test failure
+    // for the wrong reason. Any non-empty value works; the deny path never
+    // authenticates. Always inject a dummy — never forward the real key —
+    // so the doomed telemetry POST cannot exfiltrate the tester's bearer
+    // (the secret_detected emit puts $FLOWRAIL_API_KEY in the Authorization
+    // header before the loopback rejects the connection, and even an
+    // unroutable target shouldn't see real credentials in its handshake).
+    const env = {
+        ...deps.env,
+        FLOWRAIL_API_KEY: 'flowrail-selftest',
+        FLOWRAIL_MCP_URL: 'http://127.0.0.1:1',
+    };
+    const { status, stderr } = deps.runHook(binPath, buildProbePayload(), env);
+    const blocked = status === 2 && /secret pattern detected/i.test(stderr);
+    if (!blocked) {
+        // Echo a truncated stderr excerpt (same diagnostic pattern as
+        // hook-install.ts's binary self-test): the common real failure is the
+        // hook exiting 2 for a *different* reason (parse error, internal
+        // error), and "got exit 2" alone tells the tester nothing.
+        const excerpt = stderr.trim().slice(0, 300);
+        throw new env_1.InitError('hook self-test FAILED — the installed flowrail-hook did NOT block a ' +
+            'write containing a known test secret ' +
+            `(expected exit 2 + "secret pattern detected", got exit ${status}).\n` +
+            'FlowRail is installed but not actually guarding writes; a silent ' +
+            'FlowRail is worse than a failed install. Check that @flowrail/hook ' +
+            'installed cleanly and that .claude/settings.json wires the ' +
+            'flowrail-hook PreToolUse command.' +
+            (excerpt ? `\nHook stderr: ${excerpt}` : ''));
+    }
+}
+// ---------------------------------------------------------------------------
+// Production wiring
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the installed hook's bin path from ``projectRoot``. Mirrors the
+ * resolution in ``hook-install.ts``'s verifier: require the package.json,
+ * read the object-form ``bin`` entry, resolve it against the package dir.
+ *
+ * Resolution relies on ``installAndVerifyHook`` having run first against
+ * the same ``projectRoot`` (it ``npm install``s @flowrail/hook there), so
+ * @flowrail/hook need not be a declared dependency of @flowrail/init.
+ * Out of that ordering, resolution throws a clear InitError rather than a
+ * confusing crash.
+ */
+function resolveInstalledHookBinPath(projectRoot) {
+    let pkgPath;
+    try {
+        pkgPath = require.resolve(`${hook_install_1.HOOK_PACKAGE}/package.json`, {
+            paths: [projectRoot],
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new env_1.InitError(`could not resolve ${hook_install_1.HOOK_PACKAGE} for the self-test: ${detail}`);
+    }
+    let pkg;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        pkg = require(pkgPath);
+    }
+    catch (err) {
+        // A resolvable-but-unparseable package.json (truncated download, disk
+        // corruption mid-install) must surface as an actionable InitError, not
+        // a bare SyntaxError escaping into the top-level handler.
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new env_1.InitError(`${hook_install_1.HOOK_PACKAGE} package.json could not be loaded for the self-test: ${detail}`);
+    }
+    const binEntry = pkg.bin && typeof pkg.bin === 'object' ? pkg.bin[hook_install_1.HOOK_BIN] : undefined;
+    if (!binEntry) {
+        throw new env_1.InitError(`${hook_install_1.HOOK_PACKAGE} package.json has no "${hook_install_1.HOOK_BIN}" bin entry; ` +
+            'cannot run the hook self-test.');
+    }
+    return path_1.default.resolve(path_1.default.dirname(pkgPath), binEntry);
+}
+/** Production ``HookRunner`` — spawns the hook via the current node. */
+const spawnHookPreWrite = (binPath, stdin, env) => {
+    const result = (0, child_process_1.spawnSync)(process.execPath, [binPath, 'pre-write'], {
+        input: stdin,
+        env,
+        encoding: 'utf8',
+    });
+    return { status: result.status, stderr: result.stderr ?? '' };
+};
+exports.spawnHookPreWrite = spawnHookPreWrite;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@flowrail/init",
+  "version": "0.0.7",
+  "description": "One-shot FlowRail installer for Claude Code. Wires PreToolUse hooks, MCP server config, and skill markdown into a tester's repo, then probes the FlowRail server with their bearer.",
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anshumanbh/flowstate.git",
+    "directory": "packages/init"
+  },
+  "homepage": "https://github.com/anshumanbh/flowstate#readme",
+  "bugs": "https://github.com/anshumanbh/flowstate/issues",
+  "main": "dist/index.js",
+  "bin": {
+    "flowrail-init": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@flowrail/skills": "0.0.3"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.14.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.5",
+    "typescript": "^5.4.5"
+  }
+}