xcoder-dna 0.0.0-stage → 1.3.1

package/dist/cli/wbc-arg.js

@@ -0,0 +1,40 @@
+// xcoder:version 1 | xcoder:task task-7a4850 | xcoder:updated 2026-10-25T16:26:45.781Z | xcoder:subtask code-st-892a22
+// C1 — pure argv pre-extractor for the root-level `--wbc <file>` flag.
+//
+// `xcoder --wbc foo.md` has NO subcommand, so commander would reject it with
+// `commander.unknownCommand` (exit 127). The workspace already solves this class
+// of problem for `--config` by rewriting `process.argv` before
+// `program.parseAsync()` (see `extractConfigArg` in config/user-config.ts); this
+// follows that precedent exactly rather than adding a root positional argument,
+// which would change how every argument-less invocation is parsed.
+//
+// Never touches the filesystem, never throws. Path validation and workspace
+// confinement are C3's job (via C9), so there is exactly one confinement
+// implementation.
+const FLAGS = ["--wbc", "--wbs"];
+export function extractWbcArg(argv) {
+    const rest = argv.slice(0, 2);
+    let value;
+    let error;
+    for (let i = 2; i < argv.length; i++) {
+        const arg = argv[i];
+        const inline = FLAGS.find((f) => arg.startsWith(`${f}=`));
+        if (inline) {
+            value = arg.slice(inline.length + 1);
+            continue;
+        }
+        if (FLAGS.includes(arg)) {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("--")) {
+                return { argv, error: "--wbc requires a path to a WBS file" };
+            }
+            value = next;
+            i++;
+            continue;
+        }
+        rest.push(arg);
+    }
+    if (error)
+        return { argv, error };
+    return { argv: rest, value };
+}

package/dist/cli/wbc.d.ts

@@ -0,0 +1,45 @@
+import type { Command } from "commander";
+export interface WbcCliOptions {
+    wbc: string;
+    /** --dry-run: print the plan, write nothing. */
+    dryRun?: boolean;
+    /** --force: replace a record that already has progress. */
+    force?: boolean;
+    /** --no-architect: deterministic, zero-token content. */
+    noArchitect?: boolean;
+    /** --max-items <n>, clamped to MAX_ITEMS (200). */
+    maxItems?: number;
+    /** Default 3, clamped 1..8. */
+    concurrency?: number;
+    /** Passed through to createLlmClient. */
+    model?: string;
+}
+export declare function setWbcSourcePath(value: string | undefined): void;
+/** The path captured from argv, or undefined when `--wbc` was not given. */
+export declare function capturedWbc(): string | undefined;
+/**
+ * Root-level flags for the feature. Declared here so the help text and the
+ * option list live in one file; the composition root applies them.
+ */
+export declare const WBC_OPTIONS: ReadonlyArray<readonly [string, string]>;
+/** Applies the feature's root flags to `program`. */
+export declare function registerWbcFlag(program: Command): void;
+/**
+ * Runs the extraction and translates the result into an exit code and
+ * sanitised terminal output. Every attacker-influenced string goes through
+ * `sanitizeForTerminal` (C14) on the way to the terminal only.
+ */
+export declare function runWbcCli(opts: WbcCliOptions, workspaceRoot: string): Promise<void>;
+/**
+ * Root-action branch: runs the extraction when `--wbc` was captured and
+ * reports whether it handled the invocation (so the caller can return early).
+ */
+export declare function runCapturedWbc(opts: {
+    workspace: string;
+    dryRun?: boolean;
+    force?: boolean;
+    architect?: boolean;
+    maxItems?: unknown;
+    concurrency?: unknown;
+    model?: string;
+}): Promise<boolean>;

package/dist/cli/wbc.js

@@ -0,0 +1,98 @@
+// xcoder:version 3 | xcoder:task task-7a4850 | xcoder:updated 2026-10-25T16:40:07.741Z | xcoder:subtask code-st-892a22
+// C2 — the root-command surface for `xcoder --wbc <file>`.
+//
+// `--wbc` is declared on the ROOT command (the same block that owns
+// `--workspace`, `--concurrency` and `--model`), so it shows up in
+// `xcoder --help` and reuses those globals rather than declaring a second set
+// of conflicting flags. `--wbc` itself is lifted out of argv by
+// `extractWbcArg()` before `program.parseAsync()` (C1); the captured path is
+// handed in through `setWbcSourcePath()` and consumed inside the root action.
+import { extractWbsTasks } from "../task-ingest/wbs-extract.js";
+import { sanitizeForTerminal } from "../util/text-sanitize.js";
+import { log } from "../util/logger.js";
+/** Set by the composition root after `extractWbcArg()` captures the value. */
+let capturedWbcPath;
+export function setWbcSourcePath(value) {
+    capturedWbcPath = value;
+}
+/** The path captured from argv, or undefined when `--wbc` was not given. */
+export function capturedWbc() {
+    return capturedWbcPath;
+}
+/**
+ * Root-level flags for the feature. Declared here so the help text and the
+ * option list live in one file; the composition root applies them.
+ */
+export const WBC_OPTIONS = [
+    ["--wbc <path>", "with a WBS file: extract every pending item into its own scannable task run"],
+    ["--dry-run", "with --wbc: print the extraction plan and write nothing"],
+    ["--force", "with --wbc: replace task records that already have progress"],
+    ["--max-items <n>", "with --wbc: extract at most <n> pending items (default 50, max 200)"],
+    ["--no-architect", "with --wbc: use deterministic task content, spending zero tokens"],
+];
+/** Applies the feature's root flags to `program`. */
+export function registerWbcFlag(program) {
+    for (const [flags, description] of WBC_OPTIONS)
+        program.option(flags, description);
+}
+/** Commander leaves option values as strings; NaN is passed through so the
+ *  orchestrator reports `bad-options` rather than silently defaulting. */
+function numeric(value) {
+    if (value === undefined)
+        return undefined;
+    return Number(value);
+}
+/**
+ * Runs the extraction and translates the result into an exit code and
+ * sanitised terminal output. Every attacker-influenced string goes through
+ * `sanitizeForTerminal` (C14) on the way to the terminal only.
+ */
+export async function runWbcCli(opts, workspaceRoot) {
+    const result = await extractWbsTasks({
+        workspaceRoot,
+        from: opts.wbc,
+        dryRun: opts.dryRun === true,
+        force: opts.force === true,
+        detailer: opts.noArchitect === true ? null : undefined,
+        maxItems: opts.maxItems,
+        concurrency: opts.concurrency,
+    });
+    if (!result.ok) {
+        const where = result.line === undefined ? "" : ` (line ${result.line})`;
+        log.fail(`${result.code}${where}: ${sanitizeForTerminal(result.message, 300)}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (result.tasks.length === 0) {
+        log.ok(`no pending items — nothing to extract from ${sanitizeForTerminal(result.sourcePath, 100)}`);
+        return;
+    }
+    for (const task of result.tasks) {
+        const verb = task.created ? (result.dryRun ? "would create" : "created") : "unchanged";
+        log.raw(`${verb} ${task.taskId}  ${sanitizeForTerminal(result.sourcePath, 60)}:${task.line}  ` +
+            `${sanitizeForTerminal(task.stages.join(">"), 60)}  resume: ${task.nextCommand}`);
+    }
+    const c = result.counts;
+    const prefix = result.dryRun ? "dry run — would extract" : "extracted";
+    log.dim(`${prefix} ${result.tasks.length} task(s) from ${sanitizeForTerminal(result.sourcePath, 100)} — ` +
+        `${c.created} created, ${c.unchanged} unchanged, ${c.checked} checked skipped, ${c.superseded} superseded`);
+}
+/**
+ * Root-action branch: runs the extraction when `--wbc` was captured and
+ * reports whether it handled the invocation (so the caller can return early).
+ */
+export async function runCapturedWbc(opts) {
+    const from = capturedWbc();
+    if (from === undefined)
+        return false;
+    await runWbcCli({
+        wbc: from,
+        dryRun: opts.dryRun === true,
+        force: opts.force === true,
+        noArchitect: opts.architect === false,
+        maxItems: numeric(opts.maxItems),
+        concurrency: numeric(opts.concurrency),
+        model: opts.model,
+    }, opts.workspace);
+    return true;
+}

package/dist/commands/license.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from "commander";
+import { type LicenseApi } from "../license/http-client.js";
+import { type LicenseManager } from "../license/manager.js";
+/** Test seam: the registrar accepts injected dependencies. */
+export interface LicenseCommandDeps {
+    manager?: LicenseManager;
+    api?: LicenseApi;
+}
+export declare function registerLicenseCommand(program: Command, deps?: LicenseCommandDeps): void;

package/dist/commands/license.js

@@ -0,0 +1,140 @@
+// xcoder:version 2 | xcoder:task task-1d9460 | xcoder:updated 2026-10-25T17:02:40.271Z | xcoder:subtask code-st-4b0403
+/**
+ * `xcoder license …` — activation, status, refresh and seat release.
+ *
+ * Registration only: every rule lives in src/license/manager.ts so it can be
+ * unit-tested without spawning a process. This layer prints and sets an exit
+ * code.
+ *
+ * Output never contains the serial key or the raw receipt — the key comes
+ * from argv only (never an env var) and is not even held after the request.
+ */
+import * as readline from "node:readline";
+import { log } from "../util/logger.js";
+import { sanitizeForTerminal } from "../util/text-sanitize.js";
+import { createLicenseStore } from "../license/store.js";
+import { createLicenseApi, LicenseApiError } from "../license/http-client.js";
+import { createLicenseManager } from "../license/manager.js";
+import { LICENSE_API_BASE_URL, TRUST_ANCHOR } from "../license/trust-anchor.js";
+import { DENIAL_DETAIL } from "../license/types.js";
+function buildManager() {
+    return createLicenseManager({
+        store: createLicenseStore(),
+        api: createLicenseApi({ baseUrl: LICENSE_API_BASE_URL, retries: 0 }),
+        anchor: TRUST_ANCHOR,
+    });
+}
+/** Strip terminal control sequences before printing server-derived text. */
+function safe(value) {
+    return sanitizeForTerminal(value, 200);
+}
+function printActivation(rec) {
+    log.ok("license activated");
+    log.raw(`  plan:          ${safe(rec.plan)}`);
+    log.raw(`  expires at:    ${safe(rec.expiresAt)}`);
+    log.raw(`  refresh by:    ${safe(rec.refreshBy)}`);
+    log.raw(`  activation id: ${safe(rec.activationId)}`);
+    log.dim("  the serial key was not stored on this machine.");
+}
+function reportError(err) {
+    if (err instanceof LicenseApiError) {
+        log.fail(`license: ${err.message}`);
+        return;
+    }
+    log.fail(`license: ${err?.message ?? String(err)}`);
+}
+async function confirmRelease() {
+    // In a non-TTY there is nobody to answer the prompt — refuse instead of
+    // blocking forever on a stdin that will never arrive.
+    if (!process.stdin.isTTY)
+        return false;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await new Promise((resolve) => {
+            rl.question("Release this seat? The machine will need to activate again [y/N] ", resolve);
+        });
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+export function registerLicenseCommand(program, deps = {}) {
+    const manager = () => deps.manager ?? buildManager();
+    const license = program
+        .command("license")
+        .description("Manage this machine's xcoder license — activate, status, refresh, release.");
+    license
+        .command("activate <serialKey>")
+        .description("Activate this machine with a serial key.")
+        .option("--label <text>", "a human label for this seat, e.g. \"work laptop\"")
+        .action(async (serialKey, opts) => {
+        try {
+            const record = await manager().activate({ serialKey, label: opts.label });
+            printActivation(record);
+        }
+        catch (err) {
+            reportError(err);
+            process.exitCode = 1;
+        }
+    });
+    license
+        .command("status")
+        .description("Show this machine's activation state.")
+        .action(() => {
+        const mgr = manager();
+        const status = mgr.status();
+        if (!status.activation) {
+            log.fail("license: not activated — run `xcoder license activate <serial-key>`");
+            process.exitCode = 1;
+            return;
+        }
+        printActivation(status.activation);
+        if (status.verification.ok) {
+            log.ok("status: valid");
+            if (status.needsRefresh)
+                log.dim("a refresh is due — run `xcoder license refresh`.");
+        }
+        else {
+            const reason = status.verification.reason;
+            log.fail(`status: ${reason} — ${DENIAL_DETAIL[reason]}`);
+            process.exitCode = 1;
+        }
+    });
+    license
+        .command("refresh")
+        .description("Renew the offline window from the license server (needs network).")
+        .action(async () => {
+        try {
+            const record = await manager().refresh();
+            printActivation(record);
+        }
+        catch (err) {
+            reportError(err);
+            process.exitCode = 1;
+        }
+    });
+    license
+        .command("release")
+        .description("Free this seat on the license server and remove local state.")
+        .option("--yes", "skip the confirmation prompt", false)
+        .action(async (opts) => {
+        if (!opts.yes) {
+            const confirmed = await confirmRelease();
+            if (!confirmed) {
+                log.fail("license: release cancelled — pass --yes to confirm non-interactively.");
+                process.exitCode = 1;
+                return;
+            }
+        }
+        try {
+            await manager().release();
+            log.ok("license released — this machine is no longer activated.");
+        }
+        catch (err) {
+            reportError(err);
+            log.dim("local state was kept so you can retry.");
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/release.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Xcoder SDLC Release Command — `xcoder release` subcommand.
+ *
+ * Exposes the existing build-dist pipeline as a CLI subcommand.
+ * Handles version incrementing, platform selection, and output
+ * directory management using .xcoder/release/ as the default output path.
+ */
+export interface ReleaseOptions {
+    /** Target platform: win, macos, linux, or "current" for auto-detect. */
+    platform: "win" | "macos" | "linux" | "current";
+    /** Target architecture: x64, arm64. Defaults to current arch. */
+    arch: "x64" | "arm64";
+    /** Output directory for the installer. Defaults to <workspace>/.xcoder/release/. */
+    output: string;
+    /** Increment the version in package.json before building. */
+    increment?: "major" | "minor" | "patch";
+    /** Dry-run: validate inputs and print plan, don't build. */
+    dryRun: boolean;
+    /** Workspace root. */
+    workspaceRoot: string;
+}
+export interface ReleaseResult {
+    ok: boolean;
+    /** Path to the produced installer file. */
+    installerPath?: string;
+    /** Path to the SEA binary. */
+    binaryPath?: string;
+    /** Version string used for the build. */
+    version: string;
+    /** Platform built for. */
+    platform: string;
+    /** Duration of the build in ms. */
+    durationMs: number;
+    /** Error message if ok === false. */
+    error?: string;
+}
+/**
+ * Run the full release pipeline:
+ * 1. If --increment is set, bump package.json version atomically.
+ * 2. Run the build-dist pipeline (tsc → bundle → SEA → installer).
+ * 3. Write the installer to the output directory (default: .xcoder/release/).
+ * 4. Return structured result; exit non-zero on failure.
+ */
+export declare function runRelease(opts: ReleaseOptions): Promise<ReleaseResult>;

package/dist/commands/release.js

@@ -0,0 +1,180 @@
+// xcoder:version 6 | xcoder:task swarm-swarm-is-b22287 | xcoder:updated 2026-08-04T12:17:59.289Z | xcoder:subtask swarm-swarm-is-b22287/2
+/**
+ * Xcoder SDLC Release Command — `xcoder release` subcommand.
+ *
+ * Exposes the existing build-dist pipeline as a CLI subcommand.
+ * Handles version incrementing, platform selection, and output
+ * directory management using .xcoder/release/ as the default output path.
+ */
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { execSync } from "node:child_process";
+import path from "node:path";
+import { log } from "../util/logger.js";
+import { createXcoderPaths } from "../util/xcoder-paths.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function detectPlatform() {
+    switch (process.platform) {
+        case "win32": return "win";
+        case "darwin": return "macos";
+        case "linux": return "linux";
+        default: throw new Error(`Unsupported platform: ${process.platform}`);
+    }
+}
+function detectArch() {
+    return process.arch === "arm64" ? "arm64" : "x64";
+}
+function resolvePlatform(platform) {
+    return platform === "current" ? detectPlatform() : platform;
+}
+async function readPackageJson(workspaceRoot) {
+    const pkgPath = path.resolve(workspaceRoot, "package.json");
+    const data = await readFile(pkgPath, "utf-8");
+    return JSON.parse(data);
+}
+async function writePackageJson(workspaceRoot, data) {
+    const pkgPath = path.resolve(workspaceRoot, "package.json");
+    await writeFile(pkgPath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+function incrementVersion(version, level) {
+    const parts = version.split(".").map(Number);
+    if (parts.length !== 3)
+        throw new Error(`Invalid semver version: ${version}`);
+    switch (level) {
+        case "major":
+            parts[0]++;
+            parts[1] = 0;
+            parts[2] = 0;
+            break;
+        case "minor":
+            parts[1]++;
+            parts[2] = 0;
+            break;
+        case "patch":
+            parts[2]++;
+            break;
+    }
+    return parts.join(".");
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+/**
+ * Run the full release pipeline:
+ * 1. If --increment is set, bump package.json version atomically.
+ * 2. Run the build-dist pipeline (tsc → bundle → SEA → installer).
+ * 3. Write the installer to the output directory (default: .xcoder/release/).
+ * 4. Return structured result; exit non-zero on failure.
+ */
+export async function runRelease(opts) {
+    const start = Date.now();
+    const platform = resolvePlatform(opts.platform);
+    const arch = opts.arch || detectArch();
+    let pkg = await readPackageJson(opts.workspaceRoot);
+    const originalVersion = String(pkg.version ?? "0.0.0");
+    let version = originalVersion;
+    if (opts.increment) {
+        version = incrementVersion(originalVersion, opts.increment);
+        if (opts.dryRun) {
+            log.ok(`Would bump version: ${originalVersion} → ${version}`);
+        }
+        else {
+            pkg.version = version;
+            await writePackageJson(opts.workspaceRoot, pkg);
+            log.ok(`Bumped version: ${originalVersion} → ${version}`);
+        }
+    }
+    const xcoderPaths = createXcoderPaths(opts.workspaceRoot);
+    const outputDir = opts.output || xcoderPaths.releaseDir();
+    if (opts.dryRun) {
+        log.ok(`Dry-run plan:`);
+        log.ok(`  Platform:   ${platform}`);
+        log.ok(`  Arch:       ${arch}`);
+        log.ok(`  Version:    ${version}${opts.increment ? ` (was ${originalVersion})` : ""}`);
+        log.ok(`  Output:     ${outputDir}`);
+        log.ok(`  Workspace:  ${opts.workspaceRoot}`);
+        log.ok(`Dry-run complete — no build performed.`);
+        return {
+            ok: true,
+            version,
+            platform,
+            durationMs: Date.now() - start,
+        };
+    }
+    await mkdir(outputDir, { recursive: true });
+    try {
+        const rootDir = opts.workspaceRoot;
+        log.ok("[1/4] Building TypeScript...");
+        execSync("npm run build", { cwd: rootDir, stdio: "inherit" });
+        log.ok("[2/4] Bundling with esbuild...");
+        // @ts-expect-error - scripts/*.mjs have no declaration files
+        const { bundleEntry } = await import("../../scripts/bundler.mjs");
+        const bundleOut = path.join(rootDir, "dist", "xcoder-bundled.mjs");
+        await bundleEntry(path.join(rootDir, "dist", "sdlc-cli.js"), bundleOut, { minify: false });
+        log.ok("[3/4] Compiling SEA binary...");
+        // @ts-expect-error - scripts/*.mjs have no declaration files
+        const { compileSEA } = await import("../../scripts/sea-compiler.mjs");
+        const seaBinaryPath = await compileSEA(bundleOut, "xcoder", path.join(rootDir, "dist"));
+        log.ok("[4/4] Building platform installer...");
+        let installerPath;
+        switch (platform) {
+            case "win": {
+                // @ts-expect-error - scripts/*.mjs have no declaration files
+                const { buildWindowsInstaller } = await import("../../scripts/installer-windows.mjs");
+                const result = await buildWindowsInstaller(seaBinaryPath, outputDir, version, arch);
+                installerPath = result.installerPath;
+                break;
+            }
+            case "macos": {
+                // @ts-expect-error - scripts/*.mjs have no declaration files
+                const { buildMacOSInstaller } = await import("../../scripts/installer-macos.mjs");
+                const result = await buildMacOSInstaller(seaBinaryPath, outputDir, version, arch);
+                installerPath = result.installerPath;
+                break;
+            }
+            case "linux": {
+                // @ts-expect-error - scripts/*.mjs have no declaration files
+                const { buildLinuxInstaller } = await import("../../scripts/installer-linux.mjs");
+                const result = await buildLinuxInstaller(seaBinaryPath, outputDir, version, arch);
+                installerPath = result.installerPath;
+                break;
+            }
+        }
+        const durationMs = Date.now() - start;
+        log.ok(`\nRelease complete! v${version} for ${platform}-${arch}`);
+        if (installerPath)
+            log.ok(`Installer: ${installerPath}`);
+        log.ok(`Duration: ${durationMs}ms`);
+        return {
+            ok: true,
+            installerPath,
+            binaryPath: seaBinaryPath,
+            version,
+            platform,
+            durationMs,
+        };
+    }
+    catch (err) {
+        const durationMs = Date.now() - start;
+        const message = err instanceof Error ? err.message : String(err);
+        log.fail(`Release failed: ${message}`);
+        if (opts.increment && version !== originalVersion) {
+            try {
+                pkg.version = originalVersion;
+                await writePackageJson(opts.workspaceRoot, pkg);
+                log.ok(`Restored version to ${originalVersion}`);
+            }
+            catch {
+                // Best effort
+            }
+        }
+        return {
+            ok: false,
+            version,
+            platform,
+            durationMs,
+            error: message,
+        };
+    }
+}

package/dist/commands/test.d.ts

@@ -0,0 +1,50 @@
+import { Command } from "commander";
+export interface TestSuiteDescriptor {
+    name: string;
+    configPath: string;
+    npmScript: string;
+    label: string;
+    /**
+     * If set, vitest positional arguments to scope tests to specific files.
+     * Passed as direct file paths (not globs) to avoid shell expansion issues on Windows.
+     */
+    testFiles?: string[];
+}
+export interface SuiteResult {
+    suiteName: string;
+    passed: boolean;
+    durationMs: number;
+    testCount: number | null;
+    passedCount: number | null;
+    failedCount: number | null;
+    exitCode: number | null;
+    error: string | null;
+}
+/**
+ * Scan src/ directories for *.test.ts files, group by immediate parent
+ * directory, and produce one suite descriptor per folder that has tests.
+ * Skips folders with no tests. Uses the share vitest config, scoped
+ * via --include.
+ */
+export declare function generateFolderSuites(rootDir: string): TestSuiteDescriptor[];
+/**
+ * Spawn vitest as a child process for a single suite, capture
+ * stdout/stderr, enforce a per-suite timeout, and return a
+ * structured SuiteResult.
+ *
+ * Uses vitest's built-in JSON reporter so we can parse test counts
+ * for the summary. Falls back to exit-code-only pass/fail if JSON
+ * parsing fails (vitest crash, old version, etc.).
+ *
+ * If suite has testFiles, they are passed as positional arguments.
+ */
+export declare function runSuite(suite: TestSuiteDescriptor, timeoutMs: number, capture: boolean): Promise<SuiteResult>;
+/**
+ * Accept an array of SuiteResults and print a color-coded,
+ * human-readable summary to stdout.
+ */
+export declare function printSummary(results: SuiteResult[], totalDurationMs: number): void;
+/**
+ * Register the `xcoder test` subcommand.
+ */
+export declare function registerTestCommand(parent: Command): void;