productfoo 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,7 @@
+import type { BugCapsule } from "./bugCapsule.js";
+export type BugSpecContext = NonNullable<NonNullable<BugCapsule["extensions"]["foo"]>["spec_context"]>;
+/**
+ * Resolve only the packet argument positions owned by packet-aware commands.
+ * Packet content is never consulted: tasks.yaml is the complete metadata source.
+ */
+export declare function resolveBugSpecContext(root: string, domain: string, args: string[]): BugSpecContext | undefined;

package/dist-public/src/bugSpecContext.js

@@ -0,0 +1,129 @@
+import { realpathSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "./vendorYaml.js";
+const MAX_STRING_LENGTH = 4_096;
+const MAX_ARRAY_LENGTH = 100;
+const SPEC_ID = /^[a-z][a-z0-9_]{0,127}$/;
+const TASK_ID = /^T-\d{3}$/;
+const REQUIREMENT_ID = /^R-\d{3}$/;
+const PATH_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const RFC_3339 = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-](\d{2}):(\d{2}))$/;
+const PACKET_COMMANDS = {
+    asp: new Set(["validate", "migrate", "reconcile", "verify", "status", "event", "task", "verdict"]),
+    loop: new Set(["design", "check", "status", "estimate", "routine"]),
+    source: new Set(["discover", "approve", "revoke", "claim", "receipt"]),
+};
+function inside(parent, candidate) {
+    const relative = path.relative(parent, candidate);
+    return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function bounded(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= MAX_STRING_LENGTH ? value : undefined;
+}
+function packetArgument(domain, args) {
+    if (domain === "estimate")
+        return args[1];
+    const allowed = PACKET_COMMANDS[domain];
+    return allowed?.has(args[1] ?? "") ? args[2] : undefined;
+}
+function safePacketPath(value) {
+    if (path.isAbsolute(value) || value.includes("\\"))
+        return false;
+    const segments = value.split("/");
+    return segments.length >= 2 && segments[0] === "specs" && segments.every((segment) => PATH_SEGMENT.test(segment));
+}
+function rfc3339(value) {
+    const candidate = bounded(value);
+    if (!candidate)
+        return undefined;
+    const match = RFC_3339.exec(candidate);
+    if (!match)
+        return undefined;
+    const [, year, month, day, hour, minute, second, offsetHour, offsetMinute] = match;
+    if (Number(hour) > 23 || Number(minute) > 59 || Number(second) > 59 ||
+        Number(offsetHour ?? 0) > 23 || Number(offsetMinute ?? 0) > 59)
+        return undefined;
+    const calendar = new Date(Date.UTC(Number(year), Number(month) - 1, Number(day)));
+    if (calendar.getUTCFullYear() !== Number(year) ||
+        calendar.getUTCMonth() + 1 !== Number(month) ||
+        calendar.getUTCDate() !== Number(day) ||
+        Number.isNaN(Date.parse(candidate)))
+        return undefined;
+    return candidate;
+}
+/**
+ * Resolve only the packet argument positions owned by packet-aware commands.
+ * Packet content is never consulted: tasks.yaml is the complete metadata source.
+ */
+export function resolveBugSpecContext(root, domain, args) {
+    const packetArg = packetArgument(domain, args);
+    if (!packetArg || !safePacketPath(packetArg))
+        return undefined;
+    try {
+        const lexicalRoot = path.resolve(root);
+        const lexicalSpecs = path.join(lexicalRoot, "specs");
+        const lexicalPacket = path.resolve(lexicalRoot, packetArg);
+        if (!inside(lexicalSpecs, lexicalPacket) || lexicalPacket === lexicalSpecs)
+            return undefined;
+        const realRoot = realpathSync(lexicalRoot);
+        const realSpecs = realpathSync(lexicalSpecs);
+        const realPacket = realpathSync(lexicalPacket);
+        if (!inside(realRoot, realSpecs) || !inside(realSpecs, realPacket) || realPacket === realSpecs)
+            return undefined;
+        const tasksPath = path.join(realPacket, "tasks.yaml");
+        const realTasksPath = realpathSync(tasksPath);
+        if (!inside(realPacket, realTasksPath) || !inside(realSpecs, realTasksPath))
+            return undefined;
+        const document = object(parseYaml(readFileSync(realTasksPath, "utf8")));
+        if (!document)
+            return undefined;
+        const specId = bounded(document.spec_id);
+        if (!specId || !SPEC_ID.test(specId))
+            return undefined;
+        if (!specId || !Array.isArray(document.tasks) || document.tasks.length > MAX_ARRAY_LENGTH)
+            return undefined;
+        let requirementIds = [];
+        let taskIds = [];
+        if (domain === "asp" && args[1] === "task") {
+            const taskId = bounded(args[3]);
+            if (!taskId || !TASK_ID.test(taskId))
+                return undefined;
+            const matches = document.tasks
+                .map(object)
+                .filter((task) => task !== undefined && task.id === taskId);
+            if (matches.length !== 1)
+                return undefined;
+            const refs = matches[0].refs;
+            if (!Array.isArray(refs) || refs.length > MAX_ARRAY_LENGTH)
+                return undefined;
+            if (refs.some((ref) => typeof ref === "string" && ref.startsWith("R-") && !REQUIREMENT_ID.test(ref)))
+                return undefined;
+            requirementIds = refs.filter((ref) => typeof ref === "string" && REQUIREMENT_ID.test(ref));
+            if (requirementIds.some((ref) => ref.length > MAX_STRING_LENGTH))
+                return undefined;
+            taskIds = [taskId];
+        }
+        const packetPath = path.relative(realRoot, realPacket).split(path.sep).join("/");
+        if (!packetPath || packetPath.length > MAX_STRING_LENGTH || !safePacketPath(packetPath))
+            return undefined;
+        const revision = document.updated === undefined ? undefined : rfc3339(document.updated);
+        if (document.updated !== undefined && !revision)
+            return undefined;
+        return {
+            spec_id: specId,
+            packet_path: packetPath,
+            ...(revision ? { revision } : {}),
+            requirement_ids: requirementIds,
+            task_ids: taskIds,
+            provenance: "reporter_observed",
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,25 @@
+export declare const RETIRED_DIST_PACKAGE = "github:rwo572/foo-dist";
+export declare function distributionPackageName(): string;
+export declare function globalInstallCommand(): string;
+export declare function channelInstallCommand(home?: string): string;
+export type ChannelFreshnessState = "no-channel" | "unknown" | "current" | "behind";
+export type ClientKind = "repo" | "channel" | "global";
+export type ChannelFreshness = {
+    state: ChannelFreshnessState;
+    installed: string | null;
+    latest: string | null;
+    kind: ClientKind;
+};
+export declare function runningVersion(packageRoot?: string): string | null;
+export declare function isSourceCheckout(packageRoot?: string): boolean;
+export declare function runningClientKind(packageRoot?: string, home?: string): ClientKind;
+export declare function compareVersions(a: string, b: string): number;
+export declare function channelFreshnessPlan(input: {
+    installed: string | null;
+    latest: string | null;
+    kind?: ClientKind;
+}): ChannelFreshness;
+export declare function fooHome(): string;
+export declare function installedDistVersion(home?: string): string | null;
+export declare function latestPublishedVersion(registryTimeoutMs?: number): string | null;
+export declare function channelFreshness(packageRoot?: string, home?: string): ChannelFreshness;

package/dist-public/src/channelFreshness.js

@@ -0,0 +1,194 @@
+// Is the client you are running the newest one that was published?
+//
+// Nothing here self-updates: `npm install` pins whatever was published that day,
+// and nothing ever revisits it. So a release can land and productfoo keeps serving the
+// old client while cheerfully reporting a version number — which is exactly how
+// the dist channel sat on 0.1.6 for a day after 0.1.10 shipped, with no surface
+// anywhere saying so.
+//
+// The update notice (`updateNotice.ts`) covers this for testers who are working:
+// the skill server stamps every response with the current version. But it can
+// only speak to a client that CALLS the server, so it is silent for anyone
+// resolving skills locally, and silent in any session that loads no skill. That
+// leaves doctor — the one command whose whole job is "tell me if my setup is
+// wrong" — as the only surface that can answer the question unprompted. So it
+// answers it for every install, not just the channel one.
+//
+// This is an advisory doctor signal, never a block, and it is offline-safe:
+// when the newest release cannot be read, doctor says it could not check rather
+// than reporting a reassuring "current".
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readJson } from "./jsonFile.js";
+// ── The distribution-target contract ─────────────────────────────────────────
+// productfoo's canonical distribution target is the npm package this artifact ships
+// as. Every surface that names it — the update notice, doctor, the invite
+// email, `foo update`'s argv — resolves it through the functions below instead
+// of repeating a string. The published-package NAME is an open owner decision
+// (spec D-006/D-007), so the contract keeps that decision in ONE place:
+// settling it, or moving to a successor name, is a package.json edit plus this
+// module — never a grep across the tree.
+//
+// The Git install (`github:rwo572/foo-dist`) is retired, not bridged (R-009):
+// it was the private alpha channel, and the private repository it pointed at
+// stops resolving. The only deliberate survivors are commented historical
+// references, each saying why it survives.
+// Historical name of the retired private dist channel. Recorded here (and only
+// here) so the successor-seam comment below has a concrete referent; no install
+// surface may print it again.
+export const RETIRED_DIST_PACKAGE = "github:rwo572/foo-dist";
+// The successor-package seam (spec D-006): a later scope move republishes under
+// a new name and deprecates the old, and this contract is the one place the new
+// name lands. FOO_DISTRIBUTION_PACKAGE exists for the transition window — an
+// operator run whose package.json name and publish name differ — and for tests.
+export function distributionPackageName() {
+    const forced = (process.env.FOO_DISTRIBUTION_PACKAGE ?? "").trim();
+    if (forced)
+        return forced;
+    try {
+        const name = readJson(path.join(PACKAGE_ROOT, "package.json")).name;
+        if (typeof name === "string" && name.length > 0)
+            return name;
+    }
+    catch {
+        // Fall through to the shipped-name fallback below.
+    }
+    // The name this artifact ships today. One hardcoded name, inside the
+    // contract, so an unreadable package.json still yields a command a human can
+    // run — never a Git URL.
+    return "productfoo";
+}
+// The two install commands. One place, so the notice prints the same thing
+// `foo update` execs and doctor points at. `--prefix` is absolute because argv
+// is not a shell and nothing expands a tilde there.
+export function globalInstallCommand() {
+    return `npm install -g ${distributionPackageName()}`;
+}
+export function channelInstallCommand(home = fooHome()) {
+    return `npm install --prefix ${path.join(home, "versions", "dist")} ${distributionPackageName()}`;
+}
+// This file compiles to dist/src/channelFreshness.js, so two levels up is productfoo's
+// own package root — the client actually executing, whatever directory it was
+// invoked from.
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+// Deliberately not `clientVersion()` from updateNotice: that module already
+// imports compareVersions from here, and importing back would close a cycle.
+// The semantics differ anyway — null means "cannot tell", which must never be
+// compared against a real version.
+export function runningVersion(packageRoot = PACKAGE_ROOT) {
+    try {
+        const version = readJson(path.join(packageRoot, "package.json")).version;
+        return typeof version === "string" && version.length > 0 ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+// A repo checkout carries productfoo's TypeScript source; no npm install does
+// (package.json "files" ships the compiled dist-public/, never src/, and
+// test/channelFreshness.test.ts pins that against open-source/npm-files.json).
+// #892: this used to key on skills/, but the public package bundles skills/
+// since #813, so every npm install read as a checkout and could never update.
+export function isSourceCheckout(packageRoot = PACKAGE_ROOT) {
+    return existsSync(path.join(packageRoot, "src", "cli.ts"));
+}
+export function runningClientKind(packageRoot = PACKAGE_ROOT, home = fooHome()) {
+    if (isSourceCheckout(packageRoot))
+        return "repo";
+    return packageRoot.startsWith(path.join(home, "versions", "dist") + path.sep) ? "channel" : "global";
+}
+// Numeric, segment-by-segment. A string compare says "0.1.10" < "0.1.6", which
+// would hide the very release this check exists to catch.
+export function compareVersions(a, b) {
+    const parse = (value) => value.replace(/^v/, "").split(".").map((segment) => Number.parseInt(segment, 10) || 0);
+    const left = parse(a);
+    const right = parse(b);
+    for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+        const diff = (left[i] ?? 0) - (right[i] ?? 0);
+        if (diff !== 0)
+            return diff < 0 ? -1 : 1;
+    }
+    return 0;
+}
+// Pure decision, so every state is unit-testable without a network or a $HOME.
+export function channelFreshnessPlan(input) {
+    const { installed, latest } = input;
+    const kind = input.kind ?? "channel";
+    if (installed === null)
+        return { state: "no-channel", installed, latest, kind };
+    if (latest === null)
+        return { state: "unknown", installed, latest, kind };
+    return { state: compareVersions(installed, latest) < 0 ? "behind" : "current", installed, latest, kind };
+}
+export function fooHome() {
+    return process.env.FOO_HOME ?? path.join(homedir(), ".foo");
+}
+// What the `dist` channel actually has installed right now.
+export function installedDistVersion(home = fooHome()) {
+    // #892: the channel copy lives under its published name, whatever that is.
+    const manifest = path.join(home, "versions", "dist", "node_modules", ...distributionPackageName().split("/"), "package.json");
+    if (!existsSync(manifest))
+        return null;
+    try {
+        const version = readJson(manifest).version;
+        return typeof version === "string" && version.length > 0 ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Newest published release, read from the npm registry — the same source `npm
+// install` resolves. The update notice rides the skill-server header (the
+// server is the source of truth for a client that is running); this probe is
+// the offline-safe backstop doctor uses, and it needs no credentials now that
+// the target is a public package. Bounded and silent: any failure — offline, no
+// npm on PATH, a slow registry — returns null, which doctor reports as "could
+// not check", never a reassuring "current". Set FOO_SKIP_UPDATE_CHECK=1 to skip
+// the probe entirely.
+export function latestPublishedVersion(registryTimeoutMs = 5_000) {
+    if (process.env.FOO_SKIP_UPDATE_CHECK === "1")
+        return null;
+    // A test NEVER touches the registry — the same posture as telemetry, and for
+    // the same reason. The suite spawns `foo doctor` ~19 times and inherits the
+    // real HOME, so without this every one of them fired a network probe:
+    // ~0.5s each, network-dependent, and an intermittent failure whenever the
+    // network was slow enough to push a spawn toward the timeout.
+    if ((process.env.NODE_ENV ?? "").trim() === "test")
+        return null;
+    const res = spawnSync("npm", ["view", distributionPackageName(), "version", "--json"], {
+        encoding: "utf8",
+        timeout: registryTimeoutMs,
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (res.error || res.status !== 0 || typeof res.stdout !== "string")
+        return null;
+    // `npm view <pkg> version --json` prints a bare JSON string: "0.1.37".
+    try {
+        const version = JSON.parse(res.stdout);
+        if (typeof version !== "string")
+            return null;
+        const clean = version.trim().replace(/^v/, "");
+        return /^\d+(\.\d+)*$/.test(clean) ? clean : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Freshness of the client that is running right now — the one whose version the
+// user would have to change.
+//
+// A repo run is the exception, and it is the case this check was originally
+// built for: a dev checkout has no published build to be behind, but bare `foo`
+// may still be serving a stale channel install while `bin/foo` runs new code.
+// So a repo run reports the channel; an installed run reports itself.
+export function channelFreshness(packageRoot = PACKAGE_ROOT, home = fooHome()) {
+    const kind = runningClientKind(packageRoot, home);
+    const installed = kind === "repo" ? installedDistVersion(home) : runningVersion(packageRoot);
+    // Don't go to the network at all when there is nothing that could be stale.
+    if (installed === null)
+        return channelFreshnessPlan({ installed: null, latest: null, kind });
+    return channelFreshnessPlan({ installed, latest: latestPublishedVersion(), kind });
+}

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

@@ -0,0 +1,30 @@
+import { type ReportFinalizationDeps, type ReportInvocationMode } from "./errorReport.js";
+export type { PacketContext } from "./commands/asp.js";
+/**
+ * #885: one command's usage, taken from the canonical full listing so the two
+ * can never drift. Null when the listing carries no line for the command
+ * (harness-only surfaces such as `interview`), so it falls through to normal
+ * dispatch.
+ */
+export declare function domainHelp(domain: string): string | null;
+export declare const CLI_DOMAINS: Set<string>;
+export declare const CLI_SUBCOMMANDS: Record<string, readonly string[]>;
+export declare function deriveCliCommand(args: string[]): {
+    domain: string;
+    command: string;
+};
+export declare function firstRunNotice(_env?: NodeJS.ProcessEnv): string;
+export declare function reportInvocationMode(args: string[], env?: NodeJS.ProcessEnv, terminal?: {
+    stdinIsTTY: boolean;
+    stdoutIsTTY: boolean;
+    stderrIsTTY: boolean;
+}): ReportInvocationMode;
+export type MainDeps = {
+    terminal?: {
+        stdinIsTTY: boolean;
+        stdoutIsTTY: boolean;
+        stderrIsTTY: boolean;
+    };
+    report?: ReportFinalizationDeps;
+};
+export declare function main(argv: string[], deps?: MainDeps): Promise<number>;