productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/cliArgs.d.ts

@@ -0,0 +1,7 @@
+export declare function hasFlag(args: string[], flag: string): boolean;
+export declare function flagValue(args: string[], flag: string): string | undefined;
+export type FlagSpec = {
+    value?: readonly string[];
+    boolean?: readonly string[];
+};
+export declare function surplusArgs(args: string[], spec: FlagSpec): string[];

package/dist-public/src/cliArgs.js

@@ -0,0 +1,44 @@
+// argv parsing foo repeats everywhere: a boolean `--flag`, and a `--flag value`
+// whose value is the token immediately after it. Every command module reached
+// for its own `args.indexOf("--flag")` / `args[idx + 1]` inline (and one even
+// re-declared a private `flag` helper); these name the idiom once so call sites
+// read as intent.
+// Is a bare boolean flag present?
+export function hasFlag(args, flag) {
+    return args.includes(flag);
+}
+// The token immediately after `flag`, or undefined when the flag is absent (or
+// is the last token with no value following it).
+export function flagValue(args, flag) {
+    const index = args.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    return args[index + 1];
+}
+// The tokens nobody consumed.
+//
+// `flagValue` reads by `indexOf`, so it can answer "what came after --summary?"
+// but never "was there a token here I didn't look at?" — and that blind spot is
+// how `foo asp event <packet> <type> <summary>` silently dropped the summary and
+// committed `data: {}` to an append-only ledger (alpha_tester_fixes_v0 R-001).
+// A command that writes something it cannot take back must be able to see what
+// it did not read, so it can refuse instead of guess.
+//
+// A bare word in the result is a positional the caller meant as an argument; a
+// `--x` in the result is a flag this command does not have. Both are surplus.
+export function surplusArgs(args, spec) {
+    const valueFlags = new Set(spec.value ?? []);
+    const booleanFlags = new Set(spec.boolean ?? []);
+    const surplus = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (valueFlags.has(token)) {
+            index += 1; // the next token belongs to this flag, whatever it looks like
+            continue;
+        }
+        if (booleanFlags.has(token))
+            continue;
+        surplus.push(token);
+    }
+    return surplus;
+}

package/dist-public/src/codeCatalog.d.ts

@@ -0,0 +1,41 @@
+export type StoryProvenance = "structural-diff" | "agent-inference" | "repo-truth";
+export type ChangeKind = "added" | "modified" | "removed";
+export interface BehaviorStory {
+    id: string;
+    file: string;
+    change_kind: ChangeKind;
+    title: string;
+    /** The code-derived expectation: what the changed code does. Self-reported. */
+    expected_behavior: string;
+    /** Concrete code evidence (declaration names) behind the story. */
+    evidence: string[];
+    added_symbols: string[];
+    removed_symbols: string[];
+    added_lines: number;
+    removed_lines: number;
+    provenance: StoryProvenance;
+    /** Code-derived expectations are non-authoritative over intent; always true here. */
+    self_reported: boolean;
+}
+export interface SkippedFile {
+    file: string;
+    reason: string;
+}
+/** R-007: enumeration coverage is reported so a missed feature is a visible gap. */
+export interface ExtractionCoverage {
+    scanned_files: number;
+    story_files: number;
+    stories: number;
+    basis: string;
+    skipped: SkippedFile[];
+}
+export interface CatalogResult {
+    stories: BehaviorStory[];
+    coverage: ExtractionCoverage;
+}
+/**
+ * Extract one code-derived behavior story per changed source file from a unified
+ * diff. Pure and deterministic. Binary and lockfile/generated paths are skipped
+ * and listed in coverage (R-007) rather than silently dropped. Never gates.
+ */
+export declare function extractBehaviorStories(diff: string): CatalogResult;

package/dist-public/src/codeCatalog.js

@@ -0,0 +1,197 @@
+// code-catalog-rip-v0 engine, promoted to an importable module so spec-after
+// can consume it (spec-after-capture-v0 R-003: import the behavior extractor,
+// never fork it — one owner per behavior). Deterministic code->behavior-story
+// extraction from a unified diff.
+//
+// The stories are CODE-DERIVED expectations: tagged `self_reported`, provenance
+// no stronger than the extraction method, and NEVER gating. Code is evidence of
+// behavior, never authority over intent (catalog R-003/R-005). This module reads
+// text only; it never runs a test, applies a fix, or invokes a runner (R-005).
+//
+// V0a uses the deterministic `structural-diff` extractor below. V0b can swap in
+// an LLM-backed extractor that emits the same `BehaviorStory` shape with
+// provenance `agent-inference` — the type is the contract, the extractor is a
+// slope-riding adapter (spec-after R-010).
+const LOCKFILES = new Set([
+    "package-lock.json",
+    "npm-shrinkwrap.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "Cargo.lock",
+    "poetry.lock",
+    "composer.lock",
+    "Gemfile.lock",
+    "go.sum",
+]);
+/**
+ * productfoo's own bookkeeping — error reports, run caches, event logs it writes into the user's repo.
+ *
+ * These must never appear as a drift finding. A real run reported `added .foo/reports/err_*.json`
+ * as "built but never asked for": foo wrote the file, then told the user they had built something
+ * they never asked for. That is the tool littering someone's repo and then billing them for it —
+ * and it is the same complaint an alpha tester already filed about files appearing in her checkout.
+ */
+function isFooArtifact(file) {
+    return /(^|\/)\.foo\//.test(file);
+}
+function isGeneratedPath(file) {
+    const base = file.split("/").pop() ?? file;
+    if (isFooArtifact(file))
+        return true;
+    if (LOCKFILES.has(base))
+        return true;
+    return /\.(min\.js|map|snap)$/.test(base);
+}
+// Deterministic declaration detection on added/removed lines. Intentionally
+// conservative: it names symbols, it does not claim to understand them. Exported
+// declarations count at any depth; bare (non-exported) declarations only count
+// at top level so nested locals (loop vars, helpers' internals) stay out of the
+// story.
+const DECL_PATTERNS = [
+    { re: /\bexport\s+(?:default\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/, exported: true },
+    { re: /\bexport\s+(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/, exported: true },
+    { re: /\bexport\s+(?:const|let|var)\s+([A-Za-z_$][\w$]*)/, exported: true },
+    { re: /\bexport\s+(?:interface|type|enum)\s+([A-Za-z_$][\w$]*)/, exported: true },
+    { re: /\b(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/, exported: false },
+    { re: /\bclass\s+([A-Za-z_$][\w$]*)/, exported: false },
+    { re: /\b(?:const|let)\s+([A-Za-z_$][\w$]*)\s*=/, exported: false },
+    { re: /\bdef\s+([A-Za-z_$][\w$]*)/, exported: false },
+];
+function symbolsFrom(lines) {
+    const found = new Set();
+    for (const line of lines) {
+        const topLevel = /^\S/.test(line);
+        for (const { re, exported } of DECL_PATTERNS) {
+            if (!exported && !topLevel)
+                continue;
+            const m = re.exec(line);
+            if (m && m[1])
+                found.add(m[1]);
+        }
+    }
+    return [...found];
+}
+function splitFileSections(diff) {
+    const sections = [];
+    let current = null;
+    for (const line of diff.split(/\r?\n/)) {
+        if (line.startsWith("diff --git ")) {
+            if (current)
+                sections.push(current);
+            current = { header: line, body: [] };
+        }
+        else if (current) {
+            current.body.push(line);
+        }
+    }
+    if (current)
+        sections.push(current);
+    return sections;
+}
+function pathFromSection(header, body) {
+    let plus;
+    let minus;
+    for (const line of body) {
+        if (line.startsWith("+++ "))
+            plus = line.slice(4).trim();
+        else if (line.startsWith("--- "))
+            minus = line.slice(4).trim();
+    }
+    const pick = (value) => value && value !== "/dev/null" ? value.replace(/^[ab]\//, "") : undefined;
+    const fromHeader = /a\/(.+) b\/(.+)$/.exec(header);
+    return pick(plus) ?? pick(minus) ?? fromHeader?.[2] ?? header.replace("diff --git ", "");
+}
+function changeKind(body) {
+    for (const line of body) {
+        if (line.startsWith("new file mode"))
+            return "added";
+        if (line.startsWith("deleted file mode"))
+            return "removed";
+    }
+    return "modified";
+}
+function isBinary(body) {
+    return body.some((line) => line.startsWith("Binary files ") || line.startsWith("GIT binary patch"));
+}
+function buildTitle(kind, file, added) {
+    if (!added.length)
+        return `${kind} ${file}`;
+    const head = added.slice(0, 3).join(", ");
+    return `${kind} ${file} (+${head}${added.length > 3 ? ", …" : ""})`;
+}
+function listSymbols(symbols, max = 8) {
+    const shown = symbols.slice(0, max).map((s) => `\`${s}\``).join(", ");
+    return symbols.length > max ? `${shown}, +${symbols.length - max} more` : shown;
+}
+function buildExpectedBehavior(kind, file, added, removed, addedLines, removedLines) {
+    const parts = [];
+    if (kind === "added")
+        parts.push(`New file \`${file}\` (+${addedLines})`);
+    else if (kind === "removed")
+        parts.push(`Removes \`${file}\` (-${removedLines})`);
+    else
+        parts.push(`Modifies \`${file}\` (+${addedLines}/-${removedLines})`);
+    if (added.length)
+        parts.push(`adds ${listSymbols(added)}`);
+    if (removed.length)
+        parts.push(`removes ${listSymbols(removed)}`);
+    return `${parts.join("; ")}.`;
+}
+/**
+ * Extract one code-derived behavior story per changed source file from a unified
+ * diff. Pure and deterministic. Binary and lockfile/generated paths are skipped
+ * and listed in coverage (R-007) rather than silently dropped. Never gates.
+ */
+export function extractBehaviorStories(diff) {
+    const sections = splitFileSections(diff);
+    const stories = [];
+    const skipped = [];
+    let seq = 0;
+    for (const section of sections) {
+        const file = pathFromSection(section.header, section.body);
+        // productfoo's own bookkeeping is dropped outright, not "skipped". The skipped list exists so no
+        // file of YOURS is silently ignored (R-007) — but these are not your files, they are productfoo's,
+        // and reporting them back to you is the tool making its own litter your problem.
+        if (isFooArtifact(file))
+            continue;
+        if (isBinary(section.body)) {
+            skipped.push({ file, reason: "binary" });
+            continue;
+        }
+        if (isGeneratedPath(file)) {
+            skipped.push({ file, reason: "generated/lockfile" });
+            continue;
+        }
+        const added = section.body.filter((line) => line.startsWith("+") && !line.startsWith("+++"));
+        const removed = section.body.filter((line) => line.startsWith("-") && !line.startsWith("---"));
+        const addedSymbols = symbolsFrom(added.map((line) => line.slice(1)));
+        const removedSymbols = symbolsFrom(removed.map((line) => line.slice(1))).filter((symbol) => !addedSymbols.includes(symbol));
+        const kind = changeKind(section.body);
+        seq += 1;
+        stories.push({
+            id: `bs-${String(seq).padStart(3, "0")}`,
+            file,
+            change_kind: kind,
+            title: buildTitle(kind, file, addedSymbols),
+            expected_behavior: buildExpectedBehavior(kind, file, addedSymbols, removedSymbols, added.length, removed.length),
+            evidence: [...addedSymbols.map((s) => `+${s}`), ...removedSymbols.map((s) => `-${s}`)].slice(0, 12),
+            added_symbols: addedSymbols,
+            removed_symbols: removedSymbols,
+            added_lines: added.length,
+            removed_lines: removed.length,
+            provenance: "structural-diff",
+            self_reported: true,
+        });
+    }
+    return {
+        stories,
+        coverage: {
+            scanned_files: sections.length,
+            story_files: stories.length,
+            stories: stories.length,
+            basis: "unified diff: one behavior story per changed source file; symbols via declaration regex. " +
+                "Code-derived and self-reported (catalog R-001/R-003); binary and lockfile/generated paths skipped and listed.",
+            skipped,
+        },
+    };
+}

package/dist-public/src/commandContract.d.ts

@@ -0,0 +1,84 @@
+export declare const COMMAND_CONTRACT_SCHEMA_VERSION = "0.1";
+export interface FooCommandContract {
+    id: string;
+    name: string;
+    description: string;
+    /** Human argument hint; empty string when the command takes no arguments. */
+    argument_hint: string;
+    /** Repo-relative path to the reviewed human-readable command doc (R-002). */
+    docs_path: string;
+    /** Runtime-safe invocation shape: what a thin launcher actually calls (R-003). */
+    invocation: string;
+    /**
+     * What the launcher tells the agent to ask for when the user typed the
+     * command bare. The one instruction that cannot move into the handoff: the
+     * command has nothing to run on until it is answered. Empty for commands that
+     * take no argument.
+     */
+    missing_argument_ask: string;
+    /**
+     * How the agent must run the command AFTER invoking it. These normally ship
+     * in the CLI's handoff output rather than the launcher
+     * (thin-harness-launchers-v0):
+     * a harness that renders an expanded command — OpenCode, Cursor, Codex —
+     * publishes the launcher verbatim into the user's chat, so anything living
+     * there is productfoo's machinery on display. Handoff text arrives as tool output
+     * the harness collapses, and it ships with the CLI, so a wording fix reaches
+     * every user on upgrade instead of only those who rerun `foo agent setup`.
+     *
+     * The bug launcher is the narrow exception: agent-safe collection uses
+     * `--json`, which intentionally emits no handoff, and its consent boundary
+     * governs later show/send calls. Its same contract-owned steps are therefore
+     * rendered into every launcher and descriptor rather than copied elsewhere.
+     *
+     * Write these as instructions to the agent holding the runtime contract.
+     */
+    agent_steps: readonly string[];
+}
+export declare const COMMAND_HANDOFF_ALWAYS: readonly string[];
+export declare const FOO_COMMAND_CONTRACT: readonly FooCommandContract[];
+export declare function listCommandContract(): {
+    schema_version: string;
+    commands: readonly FooCommandContract[];
+};
+export declare function showCommandContract(id: string): FooCommandContract;
+export interface CommandDocDrift {
+    id: string;
+    field: "doc" | "description" | "argument_hint" | "contract" | "agent_step";
+    contract: string | null;
+    doc: string | null;
+}
+export declare function validateCommandDocs(root: string): {
+    ok: boolean;
+    drift: CommandDocDrift[];
+};
+export interface LauncherDrift {
+    file: string;
+    id: string;
+    field: "description" | "argument_hint";
+    contract: string;
+    launcher: string | null;
+}
+/**
+ * Compare committed, foo-managed launcher files against the contract.
+ * `files` are repo-relative paths (typically `git ls-files`); anything that is
+ * not a foo-managed launcher is ignored, so passing the whole tracked list is fine.
+ */
+export declare function validateCommittedLaunchers(root: string, files: readonly string[]): {
+    ok: boolean;
+    drift: LauncherDrift[];
+};
+export declare function renderCommandHandoff(entry: FooCommandContract, extraSteps?: readonly string[]): string;
+export declare function harnessMarkerPresent(env: NodeJS.ProcessEnv): boolean;
+export declare function handoffEnabled(io: {
+    isTTY: boolean;
+    env: NodeJS.ProcessEnv;
+}): boolean;
+export declare function withCommandHandoff(id: string, output: string, args: readonly string[], extraSteps?: readonly string[], io?: {
+    isTTY: boolean;
+    env: NodeJS.ProcessEnv;
+}): string;
+export declare const FOO_COMMAND_MARKER = "<!-- foo-managed-command:";
+export declare function renderLauncher(entry: FooCommandContract, opts?: {
+    grokFooFirst?: boolean;
+}): string;