@neturely/okffs 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ See [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-07-14
+### Added
+- Autopilot / "minimum interference" mode — autonomous issue → develop-PR with a decisions report ([#238](https://github.com/neturely/okffs/issues/238))
+### Fixed
+- Silent auto-PR failure in create_issue - swallowed to stderr, retry on 422 ([#247](https://github.com/neturely/okffs/issues/247))
+
+## [0.9.0] - 2026-07-11
+### Changed
+- commit_and_update: empty commit subject from whitespace-only or leading-blank-line hint ([#236](https://github.com/neturely/okffs/issues/236))
+### Added
+- `/okffs:setup` prompt + `configure` tool — configure okffs conversationally inside Claude Code (the in-chat counterpart to the `okffs setup` CLI). Claude interviews you from the same manifest the CLI uses and persists via `configure`, which writes only okffs's marked `.env` block and preserves your own variables/comments. On startup the server also stamps the configuring version and, when okffs has been upgraded and new options exist, nudges you (once) to run `/okffs:setup` ([#242](https://github.com/neturely/okffs/issues/242))
+- `okffs setup` — an interactive CLI wizard to create/update `.env` for a repo, with Quick/Full first-run modes and a sync mode that only prompts for options new since your last run (e.g. after an okffs upgrade). Runs a non-fatal GitHub sanity check and prints a config banner. Reach it via `npx @neturely/okffs setup` ([#240](https://github.com/neturely/okffs/issues/240))
+
 ## [0.8.0] - 2026-07-08
 ### Added
 - Add an issue-less "fix PR into base branch" tool (open + merge into develop, the mirror of promote_branch) ([#226](https://github.com/neturely/okffs/issues/226))
@@ -144,7 +157,9 @@ See [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `create_pull_request` commits the updated CHANGELOG onto the branch and pushes the branch before opening the PR, with non-blocking error handling ([#38](https://github.com/2b9sa2owa/okffs/issues/38)).
 - All git operations now run via `execFileSync` with argument arrays (no shell), removing command-injection risk from branch names and commit hints; tools also checkout the target branch before committing/pushing and restore the original branch afterward.
 
-[Unreleased]: https://github.com/neturely/okffs/compare/v0.8.0...HEAD
+[Unreleased]: https://github.com/neturely/okffs/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/neturely/okffs/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/neturely/okffs/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/neturely/okffs/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/neturely/okffs/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/neturely/okffs/compare/v0.5.2...v0.6.0

package/README.md

@@ -15,7 +15,17 @@ okffs is a [Model Context Protocol](https://modelcontextprotocol.io) server that
 
 ## Quick start
 
-Add a `.mcp.json` to your project root:
+**1. Run the setup wizard** from your project root:
+
+```bash
+npx @neturely/okffs setup
+```
+
+It walks you through auth, repo, and any optional features, writes a `.env`, then runs a quick GitHub sanity check. Re-run it any time (e.g. after upgrading okffs) — it only asks about options that are new since your last run. If you're happy relying on the [GitHub CLI](https://cli.github.com/) (`gh auth login`) and working inside the repo you want to manage, you can skip this step entirely — okffs works with **no config at all**.
+
+> **Already in Claude Code?** Once okffs is connected you can configure it conversationally instead — run the **`/okffs:setup`** slash command and Claude will interview you and write the `.env` for you (no terminal needed). okffs also nudges you to run it after an upgrade introduces new options.
+
+**2. Add a `.mcp.json`** to your project root:
 
 ```json
 {
@@ -28,7 +38,7 @@ Add a `.mcp.json` to your project root:
 }
 ```
 
-That's it — `npx` fetches okffs on first use, and Claude Code picks up the tools automatically. If you're signed in with the [GitHub CLI](https://cli.github.com/) (`gh auth login`) and working inside the repo you want to manage, **no other setup is needed**. To use a token or a different repo instead, see [Configuration](#configuration).
+That's it — `npx` fetches okffs on first use, and Claude Code picks up the tools automatically. To use a token or a different repo instead of the `gh`/auto-detect defaults, run `okffs setup` (above) or edit `.env` by hand — see [Configuration](#configuration).
 
 Now just ask Claude:
 
@@ -64,6 +74,7 @@ Claude infers labels (`bug`, `enhancement`, …) from the title and description
 | `update_project_status` | Moves an issue between board columns (`Backlog`, `Ready`, `In Progress`, `Review`). Needs `OKFFS_PROJECT_ENABLED`. |
 | `set_issue_fields` | Sets board Priority/Effort **and/or the native Issue Type** on an **existing** issue. Priority/Effort handle project-native and org-level Issue Fields (needs `OKFFS_PROJECT_ENABLED`); `type` is org-native and works independently. `create_issue` only sets these at creation; use this afterwards. Status stays with `update_project_status`. |
 | `update_issue` | Edits an **existing** issue's core fields — `title`, `assignees`, `labels`, `milestone`, `body` — via one PATCH with the configured token. `labels`/`assignees` replace the whole set (`[]` clears). For Priority/Effort/Type use `set_issue_fields`; for Status use `update_project_status`. |
+| `configure` | Writes okffs config to `.env` — the backend for the `/okffs:setup` prompt. Reuses the `okffs setup` wizard's manifest/serializer: updates only okffs's marked block, preserving your own variables and comments. Usually driven by `/okffs:setup`, not called directly. |
 | `delete_issue` | Closes an issue **and** deletes its branch. Destructive — needs `confirmed: true`. |
 | `delete_branch` | Deletes a branch **and** closes its issue. Destructive — needs `confirmed: true`. |
 
@@ -75,6 +86,12 @@ okffs has a built-in loop for review feedback — just ask (*"address the review
 
 By default review threads are left open for you to resolve; set `OKFFS_RESOLVE_THREADS=true` to have okffs resolve them once addressed.
 
+## Autopilot (minimum interference)
+
+For a hands-off session, ask Claude to *"fully handle this"* (or *"minimum interference"*) — or set `OKFFS_AUTOPILOT=true` to make it the default. In autopilot, Claude stops asking you to choose between options for **reversible** decisions, takes the recommended option at each fork, and drives an issue all the way to a PR into the base branch (and a base merge when `OKFFS_AUTO_MERGE_BASE=true`) — then posts an **"Autopilot decisions"** report (one line per choice, with a one-line why) to the PR and the issue, so you can redirect anything in a single message.
+
+It removes confirmation friction; it does **not** grant new powers. The hard stops always interrupt, even in autopilot: anything into `OKFFS_PROTECTED_BRANCH` (merge/tag/publish), destructive tools (`delete_issue` / `delete_branch`), anything billable (e.g. a Copilot review on a new promotion PR), and genuinely irreversible actions. And for a real *missing-information* call — where only you hold the context — Claude still asks one quick question rather than guess. Off by default.
+
 ## Keeping CLAUDE.md in sync
 
 The **`/okffs:update_guidance`** slash command reviews the changes on the current branch and maintains one okffs-owned section of your `CLAUDE.md` — `## Project Guidance (okffs usage)`, delimited by HTML markers — without ever touching your hand-written content. It's guidance curation (tools, env vars, conventions), not a changelog. Set `OKFFS_UPDATE_GUIDANCE=true` to have `create_pull_request` nudge Claude to run it at PR time; the command is always available.
@@ -107,6 +124,8 @@ Once enabled, `list_issues` shows each issue's column, priority, and effort (ord
 
 ## Configuration
 
+The quickest way to configure okffs is the wizard — `npx @neturely/okffs setup` — which writes and maintains the `.env` described below for you. The rest of this section documents what it (or you, by hand) can set.
+
 okffs resolves a **token** and a **target repository** with fallbacks, so most users need little config.
 
 **Token** (first match wins):
@@ -185,6 +204,12 @@ All optional; unset unless noted. Grouped by concern — the same groups appear
 | `OKFFS_PROMOTION_REVIEWERS` | — | Comma-separated reviewers to request on the gate PR (e.g. `copilot-pull-request-reviewer[bot]`). Only acted on when `OKFFS_PROMOTION_AUTO_REVIEW=true`. |
 | `OKFFS_PROMOTION_AUTO_REVIEW` | `false` | Opt in to auto-request those reviewers, **on gate-PR creation only** (never on re-runs). **⚠️ Cost:** Copilot code review is billable, so this charges per newly-created promotion PR. |
 
+**Autopilot (minimum interference)**
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `OKFFS_AUTOPILOT` | `false` | Default the session to [autopilot](#autopilot-minimum-interference): take the recommended option at each reversible fork, drive to a base-branch PR, and report the decisions. Hard stops (protected branch, destructive, billable, irreversible) still interrupt. Per-request activation (*"fully handle this"*) works regardless. |
+
 ## Conventions
 
 - **Branches:** `{issue-number}-{kebab-title-slug}` (title truncated to ~5 words), e.g. `42-add-hero-section-to-homepage`.

package/dist/autopilot.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Whether minimum-interference mode is on by env default (OKFFS_AUTOPILOT=true).
+ * Per-request activation ("fully handle this") is behavioural and not visible
+ * here — this only reflects the persistent default.
+ */
+export declare function autopilotEnabled(): boolean;
+/**
+ * Render the "Autopilot decisions" report block — one line per fork, each already
+ * phrased by the agent as *what was chosen* + *one-line why*. Returns null when
+ * there is nothing to report so callers omit the section cleanly rather than
+ * emitting an empty heading. Blank/whitespace-only entries are dropped. #238.
+ */
+export declare function renderAutopilotDecisions(decisions?: string[] | null): string | null;
+/** Shared schema description for the `autopilot_decisions` tool parameter. */
+export declare const AUTOPILOT_DECISIONS_DESCRIPTION: string;
+//# sourceMappingURL=autopilot.d.ts.map

package/dist/autopilot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autopilot.d.ts","sourceRoot":"","sources":["../src/autopilot.ts"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAQnF;AAED,8EAA8E;AAC9E,eAAO,MAAM,+BAA+B,QAKmC,CAAC"}

package/dist/autopilot.js

@@ -0,0 +1,42 @@
+// Autopilot ("minimum interference") — #238.
+//
+// The mode itself is behavioural: okffs can't suppress the host LLM's questions,
+// so the load-bearing piece is the always-on guidance in SERVER_INSTRUCTIONS
+// (src/server.ts), which tells the agent to take the recommended option at each
+// reversible fork, honour the hard stops, and report the decisions. This module
+// is the small amount of *plumbing* okffs owns: knowing whether the env default
+// is on, and rendering the decisions report into a PR body / issue comment in a
+// consistent shape (the host LLM supplies the content — the decisions — the same
+// way it supplies triage/fixes for address_pr_review).
+import { config } from "./config.js";
+/**
+ * Whether minimum-interference mode is on by env default (OKFFS_AUTOPILOT=true).
+ * Per-request activation ("fully handle this") is behavioural and not visible
+ * here — this only reflects the persistent default.
+ */
+export function autopilotEnabled() {
+    return config.autopilot;
+}
+/**
+ * Render the "Autopilot decisions" report block — one line per fork, each already
+ * phrased by the agent as *what was chosen* + *one-line why*. Returns null when
+ * there is nothing to report so callers omit the section cleanly rather than
+ * emitting an empty heading. Blank/whitespace-only entries are dropped. #238.
+ */
+export function renderAutopilotDecisions(decisions) {
+    // Strip a leading bullet marker (-, *, •) the caller may have already added, so
+    // "- chose X" and "chose X" both render as a single bullet rather than "- - …".
+    const items = (decisions ?? [])
+        .map((d) => d.trim().replace(/^[-*•]\s+/, "").trim())
+        .filter(Boolean);
+    if (items.length === 0)
+        return null;
+    return ["## 🤖 Autopilot decisions", ...items.map((d) => `- ${d}`)].join("\n");
+}
+/** Shared schema description for the `autopilot_decisions` tool parameter. */
+export const AUTOPILOT_DECISIONS_DESCRIPTION = "Autopilot decisions report — when driving this issue in minimum-interference " +
+    "(autopilot) mode, pass one entry per reversible fork you decided without asking, " +
+    "each phrased as 'what you chose — one-line why'. okffs renders them as an " +
+    "'Autopilot decisions' block in the PR body and the issue comment so the user has " +
+    "an audit trail to redirect in a single message. Omit when not in autopilot.";
+//# sourceMappingURL=autopilot.js.map

package/dist/autopilot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"autopilot.js","sourceRoot":"","sources":["../src/autopilot.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,EAAE;AACF,iFAAiF;AACjF,6EAA6E;AAC7E,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAChF,iFAAiF;AACjF,uDAAuD;AAEvD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,MAAM,CAAC,SAAS,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,SAA2B;IAClE,gFAAgF;IAChF,gFAAgF;IAChF,MAAM,KAAK,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC;SAC5B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;SACpD,MAAM,CAAC,OAAO,CAAC,CAAC;IACnB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO,CAAC,2BAA2B,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACjF,CAAC;AAED,8EAA8E;AAC9E,MAAM,CAAC,MAAM,+BAA+B,GAC1C,+EAA+E;IAC/E,mFAAmF;IACnF,4EAA4E;IAC5E,mFAAmF;IACnF,6EAA6E,CAAC"}

package/dist/cli/banner.d.ts

@@ -0,0 +1,17 @@
+export declare function packageVersion(): string;
+export interface BannerInfo {
+    version: string;
+    owner?: string;
+    repo?: string;
+    tokenSource: "env" | "gh" | "none";
+    baseBranch: string;
+    protectedBranch: string;
+    features: string[];
+}
+export declare function buildBannerInfo(values: Record<string, string>, resolved: {
+    owner?: string;
+    repo?: string;
+    tokenSource: "env" | "gh" | "none";
+}): BannerInfo;
+export declare function renderBanner(info: BannerInfo): string;
+//# sourceMappingURL=banner.d.ts.map

package/dist/cli/banner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"banner.d.ts","sourceRoot":"","sources":["../../src/cli/banner.ts"],"names":[],"mappings":"AAMA,wBAAgB,cAAc,IAAI,MAAM,CAQvC;AAWD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,QAAQ,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,KAAK,GAAG,IAAI,GAAG,MAAM,CAAA;CAAE,GAC9E,UAAU,CAuBZ;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAWrD"}

package/dist/cli/banner.js

@@ -0,0 +1,65 @@
+// The startup info banner: package version, resolved owner/repo, branch tiers,
+// and which optional features are active. Factored out (plain string, no prompt
+// library) so a future `okffs status` command can reuse it standalone.
+import { readFileSync } from "node:fs";
+export function packageVersion() {
+    try {
+        // dist/cli/banner.js → ../../package.json is the package root in both the
+        // published layout and local dist build.
+        return JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+    }
+    catch {
+        return "unknown";
+    }
+}
+function isTrue(v) {
+    return v === "true";
+}
+// Booleans that default ON (OKFFS_*_METADATA/INFER) are "off" only at "false".
+function isOff(v) {
+    return v === "false";
+}
+export function buildBannerInfo(values, resolved) {
+    const features = [];
+    if (isTrue(values.OKFFS_PROJECT_ENABLED))
+        features.push("Projects v2 board");
+    if (isTrue(values.OKFFS_AUTO_PR))
+        features.push("auto draft-PR on new issue");
+    if (isTrue(values.OKFFS_AUTO_MERGE_BASE))
+        features.push("auto-merge into base");
+    if (isTrue(values.OKFFS_UPDATE_DOCS))
+        features.push("auto doc updates");
+    if (isTrue(values.OKFFS_RESOLVE_THREADS))
+        features.push("auto-resolve review threads");
+    if (isTrue(values.OKFFS_UPDATE_GUIDANCE))
+        features.push("guidance sync");
+    if (isTrue(values.OKFFS_CLASSIC_PAT))
+        features.push("classic PAT (org Issue Fields)");
+    if (isTrue(values.OKFFS_PROMOTION_AUTO_REVIEW))
+        features.push("auto-request promotion reviewers");
+    if (isOff(values.OKFFS_INFER_PRIORITY) || isOff(values.OKFFS_INFER_EFFORT) || isOff(values.OKFFS_INFER_TYPE)) {
+        features.push("some inference disabled");
+    }
+    return {
+        version: packageVersion(),
+        owner: resolved.owner,
+        repo: resolved.repo,
+        tokenSource: resolved.tokenSource,
+        baseBranch: values.OKFFS_BASE_BRANCH || "(repo default)",
+        protectedBranch: values.OKFFS_PROTECTED_BRANCH || "(none)",
+        features,
+    };
+}
+export function renderBanner(info) {
+    const tokenLabel = info.tokenSource === "env" ? "GITHUB_TOKEN" : info.tokenSource === "gh" ? "gh CLI" : "none";
+    const lines = [
+        `okffs v${info.version}`,
+        `repo:      ${info.owner && info.repo ? `${info.owner}/${info.repo}` : "(unresolved)"}`,
+        `token:     ${tokenLabel}`,
+        `base:      ${info.baseBranch}`,
+        `protected: ${info.protectedBranch}`,
+        `features:  ${info.features.length ? info.features.join(", ") : "defaults only"}`,
+    ];
+    return lines.join("\n");
+}
+//# sourceMappingURL=banner.js.map

package/dist/cli/banner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"banner.js","sourceRoot":"","sources":["../../src/cli/banner.ts"],"names":[],"mappings":"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"}

package/dist/cli/env.d.ts

@@ -0,0 +1,30 @@
+export interface ParsedEnv {
+    /** Whether the file existed at all. */
+    exists: boolean;
+    /** User content before okffs's managed block — preserved verbatim (okffs var lines migrated out). */
+    preamble: string;
+    /** User content after okffs's managed block — preserved verbatim (okffs var lines migrated out). */
+    postamble: string;
+    /** okffs var values found anywhere (managed block or migrated from user content), for seeding. */
+    values: Record<string, string>;
+    /** Every okffs key that appears, set OR as a `# KEY=` placeholder, anywhere in the file. */
+    known: Set<string>;
+    /** The okffs version stamped into the managed block last time it was written, if any. */
+    configuredVersion: string | null;
+}
+export declare function parseEnv(path: string): ParsedEnv;
+export type EntryState = "set" | "declined";
+export interface Entry {
+    state: EntryState;
+    value: string;
+}
+/** Keys absent from the map are "never asked" and omitted from the output. */
+export type Collected = Record<string, Entry>;
+/**
+ * Assemble the full .env: the preserved user preamble, then okffs's managed
+ * block (regenerated from the manifest + collected values), then the preserved
+ * user postamble. Only the managed block is okffs's to rewrite.
+ */
+export declare function serializeEnv(collected: Collected, preamble: string, postamble: string, version?: string): string;
+export declare function writeEnv(path: string, contents: string): void;
+//# sourceMappingURL=env.d.ts.map

package/dist/cli/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/cli/env.ts"],"names":[],"mappings":"AAiCA,MAAM,WAAW,SAAS;IACxB,uCAAuC;IACvC,MAAM,EAAE,OAAO,CAAC;IAChB,qGAAqG;IACrG,QAAQ,EAAE,MAAM,CAAC;IACjB,oGAAoG;IACpG,SAAS,EAAE,MAAM,CAAC;IAClB,kGAAkG;IAClG,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,4FAA4F;IAC5F,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,yFAAyF;IACzF,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAMD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAgDhD;AAkDD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,UAAU,CAAC;AAC5C,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAQ9C;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CA0BhH;AAYD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE7D"}

package/dist/cli/env.js

@@ -0,0 +1,171 @@
+// Reading and (re)writing .env for the setup wizard.
+//
+// okffs owns ONLY a marker-delimited block. Everything OUTSIDE the block — the
+// user's own variables, their comments, their layout — is preserved verbatim
+// across every run. Inside the block okffs regenerates its own variables in a
+// fixed section order.
+//
+//   <user content, preserved byte-for-byte>
+//   # okffs:env:start  ── managed; regenerated each run ──
+//   OKFFS_… = …
+//   # okffs:env:end
+//   <more user content, preserved byte-for-byte>
+//
+// Recognized okffs variables found OUTSIDE the block (e.g. in a hand-written
+// .env being adopted for the first time, or one copied from .env.example) are
+// MIGRATED into the block: their value is read and re-emitted inside the block,
+// and the stray line is removed so there is never a duplicate assignment. Their
+// value is never lost — only relocated to the block okffs manages. Any comment
+// that happened to sit directly above such a line stays where it was.
+//
+// The parser also powers sync mode: a variable counts as "known" whether it is
+// set (`KEY=value`) or written as a declined placeholder (`# KEY=`), which is
+// how sync distinguishes "asked and declined" from "new, never asked".
+import { readFileSync, writeFileSync } from "node:fs";
+import { SECTIONS, allKeys } from "./manifest.js";
+const KEY_RE = /^([A-Z][A-Z0-9_]*)=(.*)$/;
+const COMMENTED_KEY_RE = /^#\s*([A-Z][A-Z0-9_]*)\s*=/;
+const START_MARKER = "okffs:env:start";
+const END_MARKER = "okffs:env:end";
+// A version stamp okffs writes into the managed block so a later run can tell
+// which okffs version last configured this .env (drives the upgrade nudge).
+const VERSION_STAMP_RE = /okffs:configured-version=(\S+)/;
+export function parseEnv(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return { exists: false, preamble: "", postamble: "", values: {}, known: new Set(), configuredVersion: null };
+    }
+    const manifestKeys = new Set(allKeys());
+    const lines = raw.split("\n");
+    // Locate okffs's managed block by its markers.
+    const startIdx = lines.findIndex((l) => l.includes(START_MARKER));
+    const endIdx = lines.findIndex((l) => l.includes(END_MARKER));
+    let preLines;
+    let managedLines;
+    let postLines;
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        preLines = lines.slice(0, startIdx);
+        managedLines = lines.slice(startIdx + 1, endIdx);
+        postLines = lines.slice(endIdx + 1);
+    }
+    else {
+        // No markers: the whole file is user content. okffs vars in it get migrated.
+        preLines = lines;
+        managedLines = [];
+        postLines = [];
+    }
+    const values = {};
+    const known = new Set();
+    // The managed block is discarded and regenerated; just harvest its values and
+    // the version stamp.
+    let configuredVersion = null;
+    for (const line of managedLines) {
+        const vm = line.match(VERSION_STAMP_RE);
+        if (vm)
+            configuredVersion = vm[1];
+        harvest(line, manifestKeys, values, known);
+    }
+    // From user content, migrate okffs var lines out (harvest + drop) and keep
+    // everything else — comments, blanks, custom vars, commented custom vars —
+    // byte-for-byte.
+    const preamble = migrate(preLines, manifestKeys, values, known);
+    const postamble = migrate(postLines, manifestKeys, values, known);
+    return { exists: true, preamble, postamble, values, known, configuredVersion };
+}
+// Record an okffs var line's key (+ value if set) without keeping the line.
+function harvest(line, manifestKeys, values, known) {
+    const cm = line.match(COMMENTED_KEY_RE);
+    if (cm && manifestKeys.has(cm[1])) {
+        known.add(cm[1]);
+        return true;
+    }
+    const m = line.match(KEY_RE);
+    if (m && manifestKeys.has(m[1])) {
+        known.add(m[1]);
+        const v = unquote(m[2].trim());
+        if (v !== "" && values[m[1]] === undefined)
+            values[m[1]] = v; // first occurrence wins (dotenv semantics)
+        return true;
+    }
+    return false;
+}
+// Harvest okffs var lines out of `lines` and return the remaining lines
+// (verbatim) joined back together.
+function migrate(lines, manifestKeys, values, known) {
+    const kept = [];
+    for (const line of lines) {
+        if (harvest(line, manifestKeys, values, known))
+            continue; // okffs var — migrated into the block
+        kept.push(line); // user content — preserved
+    }
+    return kept.join("\n");
+}
+function unquote(v) {
+    if (v.length >= 2 && ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))) {
+        return v.slice(1, -1);
+    }
+    return v;
+}
+// Quote a value only when it needs it (spaces, #, or leading/trailing space),
+// so simple values stay bare and readable.
+function quoteIfNeeded(v) {
+    if (v === "")
+        return "";
+    if (/[\s#'"]/.test(v) || v !== v.trim())
+        return JSON.stringify(v);
+    return v;
+}
+// The block boundary is a SINGLE decorative line that CONTAINS the marker, so a
+// re-parse slices exactly at it — no stray rule line can leak into the preserved
+// user content and make the file grow on each run (regen must be idempotent).
+const START_LINE = `# ${"═".repeat(22)} ${START_MARKER} ${"═".repeat(22)}`;
+const END_LINE = `# ${"═".repeat(23)} ${END_MARKER} ${"═".repeat(24)}`;
+/**
+ * Assemble the full .env: the preserved user preamble, then okffs's managed
+ * block (regenerated from the manifest + collected values), then the preserved
+ * user postamble. Only the managed block is okffs's to rewrite.
+ */
+export function serializeEnv(collected, preamble, postamble, version) {
+    const block = [
+        START_LINE,
+        "# Managed by `okffs setup` — regenerated on every run; set these via",
+        "# `okffs setup`, not by hand. Your own variables and comments OUTSIDE this",
+        "# block are left untouched.",
+        ...(version ? [`# okffs:configured-version=${version}`] : []),
+        "",
+    ];
+    for (const section of SECTIONS) {
+        const keys = [...(section.gateKey ? [section.gateKey] : []), ...section.vars.map((v) => v.key)];
+        if (!keys.some((k) => collected[k]))
+            continue; // whole section unasked — skip it
+        block.push(`# ${section.title}`);
+        if (section.blurb)
+            block.push(`# ${section.blurb}`);
+        for (const k of keys)
+            emitVar(block, k, collected);
+        block.push("");
+    }
+    block.push(END_LINE);
+    const pre = preamble.trim() ? preamble.replace(/\s+$/, "") + "\n\n" : "";
+    const post = postamble.trim() ? "\n" + postamble.replace(/^\s+/, "") : "";
+    const out = pre + block.join("\n") + post;
+    return out.replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}
+function emitVar(out, key, collected) {
+    const e = collected[key];
+    if (!e)
+        return; // never asked — omit so a later sync run offers it
+    if (e.state === "declined" || e.value === "") {
+        out.push(`# ${key}=`);
+    }
+    else {
+        out.push(`${key}=${quoteIfNeeded(e.value)}`);
+    }
+}
+export function writeEnv(path, contents) {
+    writeFileSync(path, contents, "utf8");
+}
+//# sourceMappingURL=env.js.map

package/dist/cli/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/cli/env.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import "dotenv/config";
+/** Subcommands that route to the CLI rather than the MCP server. */
+export declare const SUBCOMMANDS: Set<string>;
+/**
+ * Whether argv[2..] should be handled as a CLI invocation rather than starting
+ * the stdio MCP server. MCP hosts launch the server with no extra args, so a
+ * bare invocation always falls through to the server.
+ */
+export declare function isCliInvocation(args: string[]): boolean;
+export declare function runCli(args: string[]): Promise<number>;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AASA,OAAO,eAAe,CAAC;AAMvB,oEAAoE;AACpE,eAAO,MAAM,WAAW,aAA8B,CAAC;AAIvD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAIvD;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA0B5D"}

package/dist/cli/index.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// okffs command-line entrypoint. Dispatches subcommands (currently `setup`) and
+// is deliberately structured so `login` (Tier 3 OAuth Device Flow) and a future
+// `status` slot in without reworking the dispatcher.
+//
+// Reachable two ways:
+//   npx @neturely/okffs setup   → the package's single `okffs` bin is dist/index.js
+//                                  (the MCP server), which forwards CLI argv here.
+//   node dist/cli/index.js setup → this file run directly (local dev).
+import "dotenv/config";
+import { pathToFileURL } from "node:url";
+import { runSetup } from "./setup.js";
+import { packageVersion } from "./banner.js";
+/** Subcommands that route to the CLI rather than the MCP server. */
+export const SUBCOMMANDS = new Set(["setup", "login"]);
+const HELP_FLAGS = new Set(["help", "--help", "-h"]);
+const VERSION_FLAGS = new Set(["--version", "-v"]);
+/**
+ * Whether argv[2..] should be handled as a CLI invocation rather than starting
+ * the stdio MCP server. MCP hosts launch the server with no extra args, so a
+ * bare invocation always falls through to the server.
+ */
+export function isCliInvocation(args) {
+    const first = args[0];
+    if (!first)
+        return false;
+    return SUBCOMMANDS.has(first) || HELP_FLAGS.has(first) || VERSION_FLAGS.has(first);
+}
+export async function runCli(args) {
+    const [sub, ...rest] = args;
+    if (VERSION_FLAGS.has(sub)) {
+        console.log(packageVersion());
+        return 0;
+    }
+    if (!sub || HELP_FLAGS.has(sub)) {
+        printHelp();
+        return sub ? 0 : 1;
+    }
+    switch (sub) {
+        case "setup":
+            return runSetup(rest);
+        case "login":
+            console.error("`okffs login` (OAuth Device Flow) isn't implemented yet.\n" +
+                "For now, configure a GITHUB_TOKEN (or sign in with `gh auth login`) via `okffs setup`.");
+            return 1;
+        default:
+            console.error(`Unknown command: ${sub}\n`);
+            printHelp();
+            return 1;
+    }
+}
+function printHelp() {
+    console.log([
+        `okffs v${packageVersion()} — GitHub issue → branch → PR → merge workflow for Claude Code`,
+        "",
+        "Usage:",
+        "  npx @neturely/okffs <command>",
+        "",
+        "Commands:",
+        "  setup            Interactive wizard to create/update .env (run in a repo)",
+        "  login            (coming soon) OAuth Device Flow sign-in",
+        "",
+        "Flags:",
+        "  -h, --help       Show this help",
+        "  -v, --version    Print the okffs version",
+        "",
+        "With no command, okffs runs as an MCP server over stdio (how Claude Code launches it).",
+    ].join("\n"));
+}
+// Run directly: `node dist/cli/index.js <args>`.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    runCli(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/cli/manifest.d.ts

@@ -0,0 +1,48 @@
+export type VarKind = "text" | "boolean" | "secret" | "select";
+export interface VarSpec {
+    key: string;
+    kind: VarKind;
+    /** One-line help shown at the prompt. */
+    description: string;
+    /** Default value (as it would appear in .env). Empty string = unset. */
+    default: string;
+    /** Allowed values for kind: "select". */
+    options?: string[];
+    /** Example value shown as placeholder for free-text vars. */
+    placeholder?: string;
+}
+export interface Section {
+    id: string;
+    /** Header comment written into the generated .env. */
+    title: string;
+    /** Optional explanatory line under the header. */
+    blurb?: string;
+    vars: VarSpec[];
+    /**
+     * A gated section asks a single yes/no question first; declining it skips the
+     * whole group (its vars are written as commented placeholders). Auth & repo is
+     * the only ungated section — it is always asked.
+     */
+    gated: boolean;
+    /** Prompt shown for the gate question. */
+    gatePrompt?: string;
+    /**
+     * For a section whose gate maps onto a real boolean env var (Projects), the
+     * gate answer is persisted to this key (true/false) rather than just toggling
+     * whether the sub-vars are asked.
+     */
+    gateKey?: string;
+    /**
+     * Only offer this section when the predicate holds against values collected so
+     * far (e.g. promotion is only relevant once a protected branch is set).
+     */
+    onlyIf?: (values: Record<string, string>) => boolean;
+}
+export declare const SECTIONS: Section[];
+/** Every var key the manifest knows about, in section order. */
+export declare function allKeys(): string[];
+/** Look up a var spec by key across all sections. */
+export declare function findVar(key: string): VarSpec | undefined;
+/** Keys that make up the Quick-setup subset (auth & repo + base branch). */
+export declare const QUICK_KEYS: string[];
+//# sourceMappingURL=manifest.d.ts.map