@flowrail/init 0.0.15 → 0.0.17

package/README.md

@@ -1,27 +1,28 @@
 # @flowrail/init
 
-One-shot installer that wires FlowRail's PreToolUse hooks, MCP server config, and skill markdown into a Claude Code project.
+One-shot installer that wires FlowRail — security review for AI coding agents — into a [Claude Code](https://claude.com/claude-code) project: PreToolUse hooks, MCP server config, and agent-facing skills.
 
 ```bash
-export FLOWRAIL_API_KEY=fs_poc_<slug>_<random>    # from your FlowRail operator
+# 1. Sign up and mint an API key at https://flowrail.ai/settings/keys
+export FLOWRAIL_API_KEY=<your key>
+
+# 2. Run the installer from the repo you want FlowRail to protect
 cd ~/code/your-repo
-npx @flowrail/init
+npx @flowrail/init@latest
 ```
 
 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/guides/INSTALL.md>
+- `.mcp.json` — Claude Code MCP wiring. Tracked. Carries a `Bearer ${FLOWRAIL_API_KEY}` env-reference, never the literal key.
+- `.claude/skills/flowrail-*/SKILL.md` — the agent-facing skills (design-review, verify, dep-check, review-app, lineage).
+- `flowrail.yaml` — project config placeholder for scanner orchestration and org defaults.
+- `.gitignore` — appends `.flowrail/` so per-session runtime state (the active design review id) stays local.
 
-**Troubleshooting**: <https://github.com/anshumanbh/flowstate/blob/main/docs/guides/TROUBLESHOOTING.md>
+The installer finishes by probing `https://api.flowrail.ai/mcp` with your key to confirm end-to-end auth before exiting. A 401 gets an actionable message; transport failures get a different one.
 
-**Honest limits**: <https://github.com/anshumanbh/flowstate/blob/main/docs/guides/LIMITS.md>
+## Links
 
-This is a POC — eval-only, not for production. Source: <https://github.com/anshumanbh/flowstate>.
+- Website: <https://flowrail.ai>
+- Docs: <https://flowrail.ai/docs>
+- Mint or manage API keys: <https://flowrail.ai/settings/keys>

package/dist/ci-workflow.js

@@ -0,0 +1,258 @@
+"use strict";
+/**
+ * Canonical copy-in CI gate workflow generated by @flowrail/init.
+ *
+ * This package cannot depend on the repository workflow at runtime, so the
+ * caller-ready form is embedded here. The drift test pins the gate-authority
+ * tail to the reusable workflow maintained at the repository root.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CI_WORKFLOW_RELATIVE_PATH = void 0;
+exports.renderCiWorkflow = renderCiWorkflow;
+exports.writeCiWorkflow = writeCiWorkflow;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+exports.CI_WORKFLOW_RELATIVE_PATH = '.github/workflows/flowrail-verify.yml';
+const PROJECT_ID_PATTERN = /^prj_[0-9a-f]{32}$/;
+const PROJECT_ID_PLACEHOLDER = '__FLOWRAIL_PROJECT_ID__';
+const CI_WORKFLOW_TEMPLATE = String.raw `# generated by @flowrail/init v0.0.16 (--ci-gate)
+# workflow-protocol: 1
+name: flowrail-verify
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          # PR #102 review round 4 (P1): without this, actions/checkout
+          # persists the workflow's GitHub token in .git/config. An
+          # attacker who lands a symlink such as \`\`leak -> .git/config\`\`
+          # in the PR would have that file read + uploaded to
+          # \`\`/api/verify\`\` by the payload builder below — leaking
+          # repository credentials to the FlowRail endpoint. The
+          # symlink skip below is the second layer; this is the first.
+          persist-credentials: false
+
+      - name: Build changed-file payload
+        env:
+          BASE_SHA: @@{{ github.event.pull_request.base.sha || github.event.before }}
+          HEAD_SHA: @@{{ github.event.pull_request.head.sha || github.sha }}
+          PR_NUMBER: @@{{ github.event.pull_request.number }}
+        run: |
+          python - <<'PY'
+          import json
+          import os
+          import subprocess
+          from pathlib import Path
+
+          base = os.environ.get("BASE_SHA") or "HEAD~1"
+          head = os.environ.get("HEAD_SHA") or "HEAD"
+          raw_names = subprocess.check_output(
+              [
+                  "git",
+                  "-c",
+                  "core.quotepath=false",
+                  "diff",
+                  "-z",
+                  "--name-only",
+                  f"{base}...{head}",
+              ],
+          )
+          names = [
+              name
+              # \`\`surrogateescape\`\` so a legitimately non-UTF-8 filename in the
+              # diff cannot raise UnicodeDecodeError and fail the whole
+              # collector step; such names round-trip back to bytes for the
+              # symlink/is_file/read_text checks below.
+              for name in raw_names.decode("utf-8", "surrogateescape").split("\x00")
+              if name
+          ]
+          files = []
+          for name in names:
+              path = Path(name)
+              # PR #102 review round 4 (P1): skip symlinks. \`\`is_file\`\`
+              # follows the link, so a PR that adds \`\`leak -> /etc/passwd\`\`
+              # or \`\`leak -> .git/config\`\` would have the *target* read
+              # and uploaded. Defense paired with persist-credentials:
+              # false on the checkout step.
+              if path.is_symlink():
+                  continue
+              if not path.is_file():
+                  continue
+              try:
+                  content = path.read_text(encoding="utf-8")
+              except UnicodeDecodeError:
+                  continue
+              # The surrogateescaped \`\`name\`\` is correct for the filesystem
+              # checks above, but a lone surrogate must NOT go on the wire:
+              # the path is only a display label server-side, and strict-UTF-8
+              # response encoding would raise UnicodeEncodeError when a finding
+              # echoes it. Send a JSON-safe backslash-escaped display path.
+              display_path = os.fsencode(name).decode("utf-8", "backslashreplace")
+              files.append({"path": display_path, "content": content})
+          payload = {
+              "commit_sha": head,
+              "pr_number": int(os.environ["PR_NUMBER"]) if os.environ.get("PR_NUMBER") else None,
+              "files": files,
+          }
+          Path("flowrail-payload.json").write_text(json.dumps(payload), encoding="utf-8")
+          PY
+
+      - name: Call FlowRail verify
+        env:
+          FLOWSTATE_URL: https://api.flowrail.ai
+          PROJECT_ID: __FLOWRAIL_PROJECT_ID__
+          FLOWRAIL_TOKEN: @@{{ secrets.FLOWRAIL_PROJECT_TOKEN }}
+        run: |
+          # --fail-with-body: exit non-zero on 4xx/5xx but still write
+          # the error body to stdout so failures are debuggable. Without
+          # this flag a 401 from a wrong/unconfigured token would write
+          # a JSON error envelope to flowrail-results.json and the next
+          # step would publish a misleading "No custom guardrail findings"
+          # comment.
+          curl -sS --fail-with-body \
+            -H "Authorization: Bearer @@{FLOWRAIL_TOKEN}" \
+            -H "Content-Type: application/json" \
+            --data @flowrail-payload.json \
+            "@@{FLOWSTATE_URL}/api/verify?project_id=@@{PROJECT_ID}" \
+            > flowrail-results.json
+
+      - name: Extract PR comment
+        # Server renders the PR-comment markdown into
+        # \`\`pr_comment_markdown\`\` so the workflow does not have to ship
+        # FlowRail tooling into caller repos. \`\`actions/checkout\`\` above
+        # checked out the CALLER's repo, not flowstate, so
+        # \`\`tools/format_pr_comment.py\`\` is not available here.
+        run: |
+          python3 - <<'PY'
+          import json
+          import sys
+
+          # Degrade gracefully: a truncated/corrupt response must not crash the
+          # step with a raw traceback. The verdict-enforcement step below is the
+          # gate authority (it fails closed on malformed JSON); here we only
+          # render a comment, so fall back to a placeholder on any parse error.
+          try:
+              with open("flowrail-results.json", encoding="utf-8") as f:
+                  markdown = json.load(f).get("pr_comment_markdown")
+          except Exception as exc:
+              markdown = None
+              print(f"FlowRail: could not parse results for the PR comment: {exc}", file=sys.stderr)
+
+          # Guard against a parseable-but-non-string field (e.g. 123): writing
+          # it would raise TypeError and fail the step before the gate runs.
+          if not isinstance(markdown, str) or not markdown:
+              markdown = (
+                  "<!-- flowrail-verify-comment -->\n"
+                  "## FlowRail verify\n\n"
+                  "FlowRail could not render a PR comment (empty or unparseable "
+                  "response). The gate result is reported by the FlowRail check "
+                  "on this pull request."
+              )
+
+          # \`\`backslashreplace\`\` so a stray unpaired surrogate in the markdown
+          # (however it arose) becomes an escape rather than crashing the write
+          # and failing the job before the gate's verdict step runs.
+          with open("flowrail-comment.md", "w", encoding="utf-8", errors="backslashreplace") as f:
+              f.write(markdown)
+          PY
+
+      - name: Upsert PR comment
+        if: @@{{ github.event.pull_request.number }}
+        env:
+          GH_TOKEN: @@{{ github.token }}
+          PR_NUMBER: @@{{ github.event.pull_request.number }}
+          REPO: @@{{ github.repository }}
+        run: |
+          marker='<!-- flowrail-verify-comment -->'
+          existing=$(
+            gh api "repos/@@{REPO}/issues/@@{PR_NUMBER}/comments" \
+              --jq ".[] | select(.body | contains(\"@@{marker}\")) | .id" \
+              | head -1
+          )
+          if [ -n "$existing" ]; then
+            gh api "repos/@@{REPO}/issues/comments/@@{existing}" \
+              --method PATCH \
+              --field body="$(cat flowrail-comment.md)"
+          else
+            gh pr comment "$PR_NUMBER" --body-file flowrail-comment.md
+          fi
+
+      - name: Enforce verdict
+        run: |
+          python3 - <<'PY'
+          import json
+          import sys
+
+          try:
+              with open("flowrail-results.json", encoding="utf-8") as f:
+                  result = json.load(f)
+          except Exception as exc:
+              print("FlowRail verdict: status=contract_error mode=enforce findings=0")
+              print(f"FlowRail contract mismatch: could not load results: {exc}", file=sys.stderr)
+              raise SystemExit(1)
+
+          if not isinstance(result, dict):
+              status = None
+              mode = "enforce"
+              findings = []
+          else:
+              status = result.get("status")
+              mode = result.get("mode")
+              findings = result.get("findings") or []
+          findings_count = len(findings) if isinstance(findings, list) else 0
+          print(f"FlowRail verdict: status={status} mode={mode} findings={findings_count}")
+          if status not in {"pass", "fail"}:
+              print(f"FlowRail contract mismatch: invalid status {status!r}", file=sys.stderr)
+              raise SystemExit(1)
+          if mode not in {"enforce", "advisory"}:
+              print(f"FlowRail contract mismatch: invalid mode {mode!r}", file=sys.stderr)
+              raise SystemExit(1)
+          if status == "fail" and mode != "advisory":
+              raise SystemExit(1)
+          PY
+`
+    // String.raw preserves the escape needed to carry Markdown backticks
+    // through this TypeScript template. Remove only those deliberate escapes.
+    .split('\\`')
+    .join('`')
+    // Avoid TypeScript template interpolation while preserving GitHub syntax.
+    .split('@@{{')
+    .join('${{')
+    // Shell parameter expansion uses the same interpolation opener.
+    .split('@@{')
+    .join('${');
+function renderCiWorkflow(projectId) {
+    if (!PROJECT_ID_PATTERN.test(projectId)) {
+        throw new Error('projectId must match prj_<32 lowercase hex>');
+    }
+    return CI_WORKFLOW_TEMPLATE.replace(PROJECT_ID_PLACEHOLDER, projectId);
+}
+function writeCiWorkflow(projectRoot, projectId) {
+    const target = path_1.default.join(projectRoot, exports.CI_WORKFLOW_RELATIVE_PATH);
+    if (fs_1.default.existsSync(target)) {
+        return;
+    }
+    fs_1.default.mkdirSync(path_1.default.dirname(target), { recursive: true });
+    try {
+        fs_1.default.writeFileSync(target, renderCiWorkflow(projectId), { flag: 'wx' });
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            return;
+        }
+        throw error;
+    }
+}

package/dist/env.js

@@ -25,6 +25,12 @@ class InitError extends Error {
 exports.InitError = InitError;
 function rejectKeyArgv(argv) {
     for (const arg of argv) {
+        // Project tokens are CI-plane credentials. They never belong on the init
+        // command line, including as the value of an otherwise unknown flag.
+        if (arg.includes('fs_prj_')) {
+            throw new InitError('A FlowRail project token was supplied on argv. Project tokens are ' +
+                'credentials and must never be placed in shell history or process listings.');
+        }
         // 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.

package/dist/init.js

@@ -31,6 +31,7 @@ exports.runInit = runInit;
 const app_instance_1 = require("./app-instance");
 const claude_settings_1 = require("./claude-settings");
 const connectivity_1 = require("./connectivity");
+const ci_workflow_1 = require("./ci-workflow");
 const doctor_script_1 = require("./doctor-script");
 const env_1 = require("./env");
 const flowrail_yaml_1 = require("./flowrail-yaml");
@@ -43,6 +44,44 @@ const preflight_1 = require("./preflight");
 const repo_scan_trigger_1 = require("./repo-scan-trigger");
 const skills_1 = require("./skills");
 const verify_write_1 = require("./verify-write");
+const PROJECT_ID_PATTERN = /^prj_[0-9a-f]{32}$/;
+function parseCiGateArgs(argv) {
+    const enabled = argv.includes('--ci-gate');
+    if (!enabled)
+        return { enabled: false };
+    let projectId;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        let value;
+        if (arg === '--project-id') {
+            value = argv[i + 1];
+            if (value === undefined || value.startsWith('--')) {
+                throw new env_1.InitError('--ci-gate requires --project-id prj_<32 lowercase hex>.');
+            }
+            i++;
+        }
+        else if (arg.startsWith('--project-id=')) {
+            value = arg.slice('--project-id='.length);
+        }
+        else {
+            continue;
+        }
+        if (projectId !== undefined) {
+            throw new env_1.InitError('--project-id may be supplied only once.');
+        }
+        projectId = value;
+    }
+    if (projectId === undefined || projectId === '') {
+        throw new env_1.InitError('--ci-gate requires --project-id prj_<32 lowercase hex>.');
+    }
+    if (projectId.startsWith('fs_')) {
+        throw new env_1.InitError('--project-id accepts the public prj_ identifier, never a FlowRail token.');
+    }
+    if (!PROJECT_ID_PATTERN.test(projectId)) {
+        throw new env_1.InitError('--project-id must match prj_<32 lowercase hex>.');
+    }
+    return { enabled: true, projectId };
+}
 async function runInit(options = {}) {
     const projectRoot = options.projectRoot ?? process.cwd();
     const argv = options.argv ?? process.argv.slice(2);
@@ -51,6 +90,9 @@ async function runInit(options = {}) {
     const gitChecker = options.gitChecker ?? git_check_1.isMcpJsonGitTracked;
     const noScan = argv.includes('--no-scan') || argv.includes('--no-retro-scan');
     (0, env_1.rejectKeyArgv)(argv);
+    // Validate all CI-gate inputs before reading or writing project state. A
+    // placeholder or token-shaped value must never leave a partial install.
+    const ciGate = parseCiGateArgs(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
@@ -79,6 +121,10 @@ async function runInit(options = {}) {
     }
     (0, flowrail_yaml_1.writeFlowrailYaml)(projectRoot);
     log('✓ wrote flowrail.yaml');
+    if (ciGate.enabled) {
+        (0, ci_workflow_1.writeCiWorkflow)(projectRoot, ciGate.projectId);
+        log(`✓ wrote ${ci_workflow_1.CI_WORKFLOW_RELATIVE_PATH}`);
+    }
     (0, gitignore_1.appendFlowrailToGitignore)(projectRoot);
     log('✓ ensured .flowrail/ is in .gitignore');
     (0, gitignore_1.appendMcpJsonToGitignore)(projectRoot);
@@ -122,13 +168,19 @@ async function runInit(options = {}) {
     // covers unexpected throws (e.g. an unwritable .flowrail/).
     try {
         const rebind = argv.includes('--rebind') || env['FLOWRAIL_APP_REBIND'] === '1';
+        const appRegistrar = options.appRegistrar;
+        const registerApp = appRegistrar === undefined
+            ? undefined
+            : async (args) => (await appRegistrar(args)) ?? {
+                error: 'empty app registration response',
+            };
         const appResult = await (0, app_instance_1.ensureAppInstance)({
             projectRoot,
             mcpBaseUrl,
             apiKey,
             rebind,
             log,
-            registerApp: options.appRegistrar,
+            registerApp,
         });
         log(`✓ app instance ${appResult.appInstanceId} (${appResult.status}) — .flowrail/app.json`);
     }

package/package.json

@@ -1,19 +1,13 @@
 {
   "name": "@flowrail/init",
-  "version": "0.0.15",
-  "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.",
+  "version": "0.0.17",
+  "description": "One-shot FlowRail installer for Claude Code. Wires PreToolUse hooks, MCP server config, and skill markdown into your repo, then probes the FlowRail server with your API key.",
   "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",
+  "homepage": "https://flowrail.ai",
   "main": "dist/index.js",
   "bin": {
     "flowrail-init": "dist/index.js"
@@ -31,7 +25,7 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@flowrail/skills": "0.0.6"
+    "@flowrail/skills": "0.0.7"
   },
   "devDependencies": {
     "@types/jest": "^29.5.12",