felenova-backlog 0.1.0

package/dist/api.js

@@ -0,0 +1,104 @@
+/**
+ * The single HTTP call site in the CLI (DECISION-025). The CLI speaks REST `/v1` with a PAT:
+ * one call per command, the same `{ error, message }` refusal contract as `/mcp`, and no
+ * retries — every write in the register is non-idempotent.
+ *
+ * `src/no-stray-fetch.test.ts` fails the build if any other module calls `fetch`.
+ */
+/** A refusal the CLI can render. `status: 0` means the request never reached the service. */
+export class ApiError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+        this.code = code;
+    }
+}
+const DEFAULT_TIMEOUT_MS = 15_000;
+function joinUrl(base, path) {
+    const root = base.replace(/\/+$/, '');
+    return path.startsWith('/') ? `${root}${path}` : `${root}/${path}`;
+}
+/**
+ * One request. A 2xx JSON body is parsed and returned (`204` and an empty body are `null`);
+ * anything else throws `ApiError` built from the service's `{ error, message }`, and a body
+ * that is not that shape is `internal`. A transport failure is `status: 0`/`unreachable`.
+ */
+export async function request(cfg, token, method, path, body) {
+    if (!token) {
+        throw new ApiError(0, 'token_required', 'no PAT available — set BACKLOG_TOKEN or run: backlog init');
+    }
+    const target = joinUrl(cfg.url, path);
+    const headers = {
+        Authorization: `Bearer ${token}`,
+        accept: 'application/json',
+        'X-Backlog-Client': 'cli',
+        'X-Backlog-Actor': 'human',
+    };
+    const init = { method, headers };
+    if (body !== undefined) {
+        headers['content-type'] = 'application/json';
+        init.body = JSON.stringify(body);
+    }
+    init.signal = AbortSignal.timeout(cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const fetchImpl = cfg.fetchImpl ?? fetch;
+    let response;
+    try {
+        response = await fetchImpl(target, init);
+    }
+    catch {
+        // Deliberately swallows the cause: a transport error can carry the request, and the
+        // request carries the Authorization header.
+        throw new ApiError(0, 'unreachable', cfg.url);
+    }
+    const text = await response.text().catch(() => '');
+    if (!response.ok) {
+        let code = 'internal';
+        let message = '';
+        try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed === 'object' && parsed !== null) {
+                const record = parsed;
+                if (typeof record.error === 'string' && record.error !== '')
+                    code = record.error;
+                if (typeof record.message === 'string')
+                    message = record.message;
+            }
+        }
+        catch {
+            // a non-JSON body (a proxy's HTML 502, say) is `internal`
+        }
+        throw new ApiError(response.status, code, message);
+    }
+    if (response.status === 204 || text.trim() === '')
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new ApiError(response.status, 'internal', 'the service returned a malformed response');
+    }
+}
+export const get = (cfg, token, path) => request(cfg, token, 'GET', path);
+export const post = (cfg, token, path, body) => request(cfg, token, 'POST', path, body ?? {});
+export const patch = (cfg, token, path, body) => request(cfg, token, 'PATCH', path, body ?? {});
+export const del = (cfg, token, path) => request(cfg, token, 'DELETE', path);
+/** A config + token bound once, so a command never handles the token itself. */
+export function createClient(opts) {
+    const cfg = {
+        url: opts.url,
+        project: opts.project,
+        fetchImpl: opts.fetchImpl,
+        timeoutMs: opts.timeoutMs,
+    };
+    return {
+        url: opts.url,
+        get: (path) => get(cfg, opts.token, path),
+        post: (path, body) => post(cfg, opts.token, path, body),
+        patch: (path, body) => patch(cfg, opts.token, path, body),
+        del: (path) => del(cfg, opts.token, path),
+    };
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

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

package/dist/cache.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The offline half of `backlog status` (PRODUCT-SPEC §12). Nothing here is authoritative:
+ * the cache is a rendering of one successful read, kept so a plane, a train or a dead Fly
+ * machine still leaves `status` with something to print. It is never consulted for a write,
+ * never merged, and never read by any other command.
+ *
+ * It is gitignored (`init` adds `.backlog/`, and `status` adds it too when the repo has a
+ * `.gitignore`), and it holds **no token** — only what `/v1` already answered.
+ */
+export declare const CACHE_DIR = ".backlog";
+export declare const CACHE_FILE = ".backlog/cache.json";
+/** What `status` renders, plus the two fields that say which view this is. */
+export interface StatusCachePayload {
+    project: string;
+    url: string;
+    role: string | null;
+    tracks: unknown[];
+    items: unknown[];
+}
+export interface StatusCache extends StatusCachePayload {
+    /** When the service last answered — printed verbatim in the `cached from …` line. */
+    fetched_at: string;
+}
+export declare function cachePath(root: string): string;
+/**
+ * Writes the cache (mode 644 in a 755 directory) and returns its path.
+ *
+ * Write-then-rename, not write-in-place: the moment this function is *most* likely to run
+ * is the moment the service is flaky, and a process killed halfway through a truncating
+ * write would leave `status --offline` with a half-JSON file — which `readStatusCache`
+ * correctly treats as no cache at all, destroying a perfectly good earlier view. The bytes
+ * therefore land in a sibling temp file that nobody reads, and `rename(2)` — atomic within
+ * a directory — swaps it in. A kill before the rename leaves the previous cache intact.
+ *
+ * The five payload fields are copied one by one rather than spread: the cache is a
+ * committed-adjacent file, and an extra field appearing on a caller's object (a credential
+ * among them) must not be able to ride along into it.
+ */
+export declare function writeStatusCache(root: string, payload: StatusCachePayload, now?: Date): string;
+/**
+ * Reads the cache for exactly this `(url, project)`. Anything else — absent, unreadable,
+ * malformed, or written against another service or project — is `null`: a stale view of a
+ * different register is worse than no view at all.
+ */
+export declare function readStatusCache(root: string, target: {
+    url: string;
+    project: string;
+}): StatusCache | null;
+/**
+ * Adds `.backlog/` to an existing `.gitignore`. Returns whether it wrote. A repo with no
+ * `.gitignore` has made a choice, so this never creates one — the same rule `init` follows.
+ */
+export declare function gitignoreCache(root: string): boolean;

package/dist/cache.js

@@ -0,0 +1,114 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * The offline half of `backlog status` (PRODUCT-SPEC §12). Nothing here is authoritative:
+ * the cache is a rendering of one successful read, kept so a plane, a train or a dead Fly
+ * machine still leaves `status` with something to print. It is never consulted for a write,
+ * never merged, and never read by any other command.
+ *
+ * It is gitignored (`init` adds `.backlog/`, and `status` adds it too when the repo has a
+ * `.gitignore`), and it holds **no token** — only what `/v1` already answered.
+ */
+export const CACHE_DIR = '.backlog';
+export const CACHE_FILE = `${CACHE_DIR}/cache.json`;
+const GITIGNORE_ENTRY = `${CACHE_DIR}/`;
+export function cachePath(root) {
+    return join(root, CACHE_FILE);
+}
+/**
+ * Writes the cache (mode 644 in a 755 directory) and returns its path.
+ *
+ * Write-then-rename, not write-in-place: the moment this function is *most* likely to run
+ * is the moment the service is flaky, and a process killed halfway through a truncating
+ * write would leave `status --offline` with a half-JSON file — which `readStatusCache`
+ * correctly treats as no cache at all, destroying a perfectly good earlier view. The bytes
+ * therefore land in a sibling temp file that nobody reads, and `rename(2)` — atomic within
+ * a directory — swaps it in. A kill before the rename leaves the previous cache intact.
+ *
+ * The five payload fields are copied one by one rather than spread: the cache is a
+ * committed-adjacent file, and an extra field appearing on a caller's object (a credential
+ * among them) must not be able to ride along into it.
+ */
+export function writeStatusCache(root, payload, now = new Date()) {
+    const dir = join(root, CACHE_DIR);
+    mkdirSync(dir, { recursive: true, mode: 0o755 });
+    const path = cachePath(root);
+    const body = {
+        fetched_at: now.toISOString(),
+        project: payload.project,
+        url: payload.url,
+        role: payload.role,
+        tracks: payload.tracks,
+        items: payload.items,
+    };
+    const tmp = `${path}.tmp-${process.pid.toString(36)}${Date.now().toString(36)}`;
+    try {
+        writeFileSync(tmp, `${JSON.stringify(body, null, 2)}\n`, { mode: 0o644 });
+        // A permissive umask widens a create mode, and this file is committed-adjacent: it must
+        // be readable, and it must not be writable by anyone else.
+        if (process.platform !== 'win32')
+            chmodSync(tmp, 0o644);
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        rmSync(tmp, { force: true });
+        throw err;
+    }
+    if (process.platform !== 'win32') {
+        chmodSync(dir, 0o755);
+        chmodSync(path, 0o644);
+    }
+    return path;
+}
+/**
+ * Reads the cache for exactly this `(url, project)`. Anything else — absent, unreadable,
+ * malformed, or written against another service or project — is `null`: a stale view of a
+ * different register is worse than no view at all.
+ */
+export function readStatusCache(root, target) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(cachePath(root), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return null;
+    const doc = raw;
+    if (typeof doc.fetched_at !== 'string' || doc.fetched_at === '')
+        return null;
+    if (doc.project !== target.project)
+        return null;
+    if (doc.url !== target.url)
+        return null;
+    return {
+        fetched_at: doc.fetched_at,
+        project: doc.project,
+        url: doc.url,
+        role: typeof doc.role === 'string' ? doc.role : null,
+        tracks: Array.isArray(doc.tracks) ? doc.tracks : [],
+        items: Array.isArray(doc.items) ? doc.items : [],
+    };
+}
+/**
+ * Adds `.backlog/` to an existing `.gitignore`. Returns whether it wrote. A repo with no
+ * `.gitignore` has made a choice, so this never creates one — the same rule `init` follows.
+ */
+export function gitignoreCache(root) {
+    const path = join(root, '.gitignore');
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    const present = new Set(text.split('\n').map((line) => line.trim()));
+    if (present.has(GITIGNORE_ENTRY))
+        return false;
+    const prefix = text === '' || text.endsWith('\n') ? text : `${text}\n`;
+    writeFileSync(path, `${prefix}\n# backlog\n${GITIGNORE_ENTRY}\n`, 'utf8');
+    return true;
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

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

package/dist/commands/common.d.ts

@@ -0,0 +1,59 @@
+import { type ApiClient } from '../api.js';
+import { type TargetFlags } from '../config.js';
+import { type ErrorContext } from '../errors.js';
+/**
+ * What every command shares: resolve the config and the token, bind one client, and turn
+ * every refusal into exactly one sentence (Global Constraints — "one human sentence per
+ * refusal", and `explain` needs `ctx.url` or the `unreachable`/`internal` rows degrade).
+ *
+ * A command is a pure function of `{ cwd, home, env, fetchImpl }` plus its flags and returns
+ * `{ ok, lines }`; `src/index.ts` prints the lines and turns `ok` into the exit code. Nothing
+ * here reads `process`, so the tests run against a temp cwd and a temp HOME.
+ */
+export interface CommandIo {
+    cwd: string;
+    home: string;
+    env: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch | undefined;
+}
+export interface CommandResult {
+    ok: boolean;
+    lines: string[];
+}
+/** A refusal the CLI decided on its own (a missing config, a bad flag) — already a sentence. */
+export declare class CommandError extends Error {
+    constructor(message: string);
+}
+export interface CommandContext {
+    url: string;
+    project: string;
+    conductorDir: string;
+    /** The directory the config lives in — the repo root, and where `.backlog/` goes. */
+    root: string;
+    client: ApiClient;
+    /** Passed to `explain` on every refusal. */
+    ctx: ErrorContext;
+}
+/**
+ * The config file is mandatory for every command: an env-only invocation would work, but a
+ * repo with no `backlog.config.json` has not been initialised and the only useful thing to
+ * say is which command fixes that.
+ */
+export declare function resolveContext(command: string, io: CommandIo, flags: TargetFlags): CommandContext;
+/** One line for anything a command can throw. `ApiError` goes through the shipped table. */
+export declare function renderFailure(err: unknown, ctx: ErrorContext): string;
+/**
+ * Resolve, run, and render. `body` may throw anything above; a non-`Error` throw is
+ * re-thrown, because a bug should not be dressed up as a refusal.
+ */
+export declare function runCommand(command: string, io: CommandIo, flags: TargetFlags, body: (ctx: CommandContext) => Promise<CommandResult>): Promise<CommandResult>;
+/** `--json` prints the payload and nothing else — the only escape hatch from the sentences. */
+export declare function jsonResult(payload: unknown): CommandResult;
+/** JSON from the service is unvalidated: read it tolerantly, never crash on a missing field. */
+export declare function asRecord(value: unknown): Record<string, unknown>;
+export declare function asArray(value: unknown): unknown[];
+export declare function text(value: unknown, fallback?: string): string;
+/** `1 item`, `2 items` — a count the reader does not have to forgive. */
+export declare function plural(count: number, one: string, many?: string): string;
+/** Pads a column without letting a long value push the rest of the row out of line. */
+export declare function pad(value: string, width: number): string;

package/dist/commands/common.js

@@ -0,0 +1,94 @@
+import { dirname } from 'node:path';
+import { ApiError, createClient } from '../api.js';
+import { CONFIG_FILENAME, ConfigError, loadConfig, resolveTarget, } from '../config.js';
+import { explain } from '../errors.js';
+import { resolveToken, TokenError } from '../token.js';
+/** A refusal the CLI decided on its own (a missing config, a bad flag) — already a sentence. */
+export class CommandError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CommandError';
+    }
+}
+/**
+ * The config file is mandatory for every command: an env-only invocation would work, but a
+ * repo with no `backlog.config.json` has not been initialised and the only useful thing to
+ * say is which command fixes that.
+ */
+export function resolveContext(command, io, flags) {
+    const loaded = loadConfig(io.cwd);
+    if (!loaded) {
+        throw new CommandError(`no ${CONFIG_FILENAME} in ${io.cwd} or any directory above it — run: backlog init`);
+    }
+    const target = resolveTarget(flags, io.env, io.cwd);
+    const token = resolveToken(io.env, io.home);
+    return {
+        url: target.url,
+        project: target.project,
+        conductorDir: target.conductor_dir,
+        root: dirname(loaded.path),
+        client: createClient({
+            url: target.url,
+            token,
+            project: target.project,
+            ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}),
+        }),
+        ctx: { project: target.project, url: target.url, command },
+    };
+}
+/** One line for anything a command can throw. `ApiError` goes through the shipped table. */
+export function renderFailure(err, ctx) {
+    if (err instanceof ApiError)
+        return explain(err, ctx);
+    if (err instanceof CommandError || err instanceof ConfigError || err instanceof TokenError) {
+        return err.message;
+    }
+    if (err instanceof Error && err.message !== '')
+        return err.message;
+    throw err;
+}
+/**
+ * Resolve, run, and render. `body` may throw anything above; a non-`Error` throw is
+ * re-thrown, because a bug should not be dressed up as a refusal.
+ */
+export async function runCommand(command, io, flags, body) {
+    let ctx;
+    try {
+        ctx = resolveContext(command, io, flags);
+    }
+    catch (err) {
+        return { ok: false, lines: [renderFailure(err, { command })] };
+    }
+    try {
+        return await body(ctx);
+    }
+    catch (err) {
+        return { ok: false, lines: [renderFailure(err, ctx.ctx)] };
+    }
+}
+/** `--json` prints the payload and nothing else — the only escape hatch from the sentences. */
+export function jsonResult(payload) {
+    return { ok: true, lines: [JSON.stringify(payload, null, 2)] };
+}
+/* ------------------------------------------------------- shared payload readers */
+/** JSON from the service is unvalidated: read it tolerantly, never crash on a missing field. */
+export function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+export function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+export function text(value, fallback = '-') {
+    return typeof value === 'string' && value !== '' ? value : fallback;
+}
+/** `1 item`, `2 items` — a count the reader does not have to forgive. */
+export function plural(count, one, many = `${one}s`) {
+    return `${count} ${count === 1 ? one : many}`;
+}
+/** Pads a column without letting a long value push the rest of the row out of line. */
+export function pad(value, width) {
+    return value.length >= width ? value : value.padEnd(width, ' ');
+}
+//# sourceMappingURL=common.js.map

package/dist/commands/common.js.map

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

package/dist/commands/export.d.ts

@@ -0,0 +1,20 @@
+import { type CommandIo, type CommandResult } from './common.js';
+/**
+ * `backlog export [outDir]` — the snapshot → markdown writer, wired to the config.
+ *
+ * It is deliberately **snapshot-only**. The service ships 36 MCP tools and none of them is an
+ * export group: there is no `export_markdown` to call (MIG-001 owns it), and re-implementing
+ * the serializer client-side would put a second renderer of the canonical format in the tree —
+ * exactly what `packages/core`'s markdown module exists to prevent. So with no snapshot the
+ * command says what to run and exits 1, and the exporter itself is untouched.
+ *
+ * The config supplies the project (for that sentence) and the default output directory (the
+ * repo the config lives in). Nothing here talks to the service, so `export` needs no token.
+ */
+export declare const DEFAULT_SNAPSHOT = "backlog-snapshot.json";
+export interface ExportFlags {
+    /** The positionals: `[]`, `[outDir]`, or the shipped `[snapshot, outDir]` form. */
+    positionals: string[];
+    snapshot?: string | undefined;
+}
+export declare function runExport(io: CommandIo, flags: ExportFlags): Promise<CommandResult>;

package/dist/commands/export.js

@@ -0,0 +1,56 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { exportFromSnapshotFile } from '../export.js';
+import { CommandError, renderFailure, resolveContext, } from './common.js';
+/**
+ * `backlog export [outDir]` — the snapshot → markdown writer, wired to the config.
+ *
+ * It is deliberately **snapshot-only**. The service ships 36 MCP tools and none of them is an
+ * export group: there is no `export_markdown` to call (MIG-001 owns it), and re-implementing
+ * the serializer client-side would put a second renderer of the canonical format in the tree —
+ * exactly what `packages/core`'s markdown module exists to prevent. So with no snapshot the
+ * command says what to run and exits 1, and the exporter itself is untouched.
+ *
+ * The config supplies the project (for that sentence) and the default output directory (the
+ * repo the config lives in). Nothing here talks to the service, so `export` needs no token.
+ */
+export const DEFAULT_SNAPSHOT = 'backlog-snapshot.json';
+export async function runExport(io, flags) {
+    let ctx;
+    try {
+        // `export` needs the config (the project slug and the repo root), not a token.
+        ctx = resolveContext('export', io, {});
+    }
+    catch (err) {
+        return { ok: false, lines: [renderFailure(err, { command: 'export' })] };
+    }
+    const positionals = flags.positionals.filter((value) => value !== '');
+    const here = (value) => (isAbsolute(value) ? value : resolve(io.cwd, value));
+    // Two positionals is the shipped `backlog export <snapshot> <outDir>` invocation; one is the
+    // new `backlog export <outDir>`; none writes back into the repo the config was found in.
+    const outDir = positionals.length >= 2
+        ? here(positionals[1])
+        : positionals[0]
+            ? here(positionals[0])
+            : ctx.root;
+    const snapshot = flags.snapshot
+        ? here(flags.snapshot)
+        : positionals.length >= 2
+            ? here(positionals[0])
+            : join(ctx.root, DEFAULT_SNAPSHOT);
+    try {
+        if (!existsSync(snapshot)) {
+            throw new CommandError(`export needs a snapshot until export_markdown ships (MIG-001) — run: backlog import . --project ${ctx.project} --write`);
+        }
+        const written = await exportFromSnapshotFile(snapshot, outDir);
+        const items = written.filter((rel) => rel.includes('/items/')).length;
+        return {
+            ok: true,
+            lines: [`wrote ${written.length} files under ${outDir} (${items} items)`],
+        };
+    }
+    catch (err) {
+        return { ok: false, lines: [renderFailure(err, ctx.ctx)] };
+    }
+}
+//# sourceMappingURL=export.js.map

package/dist/commands/export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../../src/commands/export.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EACL,YAAY,EAGZ,aAAa,EACb,cAAc,GACf,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AAQxD,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,EAAa,EAAE,KAAkB;IAC/D,IAAI,GAAsC,CAAC;IAC3C,IAAI,CAAC;QACH,+EAA+E;QAC/E,GAAG,GAAG,cAAc,CAAC,QAAQ,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC;IAC3E,CAAC;IAED,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;IACtE,MAAM,IAAI,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;IAC7F,6FAA6F;IAC7F,yFAAyF;IACzF,MAAM,MAAM,GACV,WAAW,CAAC,MAAM,IAAI,CAAC;QACrB,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;QACtB,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;YACd,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YACtB,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;IACjB,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ;QAC7B,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;QACtB,CAAC,CAAC,WAAW,CAAC,MAAM,IAAI,CAAC;YACvB,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YACtB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;IAEvC,IAAI,CAAC;QACH,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,YAAY,CACpB,mGAAmG,GAAG,CAAC,OAAO,UAAU,CACzH,CAAC;QACJ,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,sBAAsB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC/D,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;QACtE,OAAO;YACL,EAAE,EAAE,IAAI;YACR,KAAK,EAAE,CAAC,SAAS,OAAO,CAAC,MAAM,gBAAgB,MAAM,KAAK,KAAK,SAAS,CAAC;SAC1E,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;IAC7D,CAAC;AACH,CAAC"}

package/dist/commands/matrix.d.ts

@@ -0,0 +1,16 @@
+import type { TargetFlags } from '../config.js';
+import { type CommandIo, type CommandResult } from './common.js';
+/**
+ * `backlog matrix init <track> [--force]` — scaffolds one QA row per locked criterion (§5.6).
+ * The service owns the scaffold, the row ids and the refusal; the CLI prints what came back
+ * and, on a `conflict`, adds the one thing the service's sentence cannot say: what `--force`
+ * actually does, which is *add* rows for uncovered criteria and never rewrite an existing one.
+ */
+export interface MatrixInitFlags extends TargetFlags {
+    track: string;
+    force?: boolean | undefined;
+    json?: boolean | undefined;
+}
+/** `--force` is a CLI flag, so the service's own sentence cannot name it. */
+export declare const FORCE_HINT = "--force adds rows only for criteria that have none; it never rewrites an existing row";
+export declare function runMatrixInit(io: CommandIo, flags: MatrixInitFlags): Promise<CommandResult>;

package/dist/commands/matrix.js

@@ -0,0 +1,48 @@
+import { ApiError } from '../api.js';
+import { explain } from '../errors.js';
+import { asArray, asRecord, CommandError, jsonResult, pad, plural, runCommand, text, } from './common.js';
+/** `--force` is a CLI flag, so the service's own sentence cannot name it. */
+export const FORCE_HINT = '--force adds rows only for criteria that have none; it never rewrites an existing row';
+/** `{ item: 'PLG-001', ac: 1 }` → `PLG-001 AC1`; a legacy row names its README rule. */
+function criterionLabel(value) {
+    const ref = asRecord(value);
+    if (typeof ref.item === 'string' && typeof ref.ac === 'number')
+        return `${ref.item} AC${ref.ac}`;
+    if (typeof ref.legacy === 'string')
+        return `legacy ${ref.legacy}`;
+    return '(unlinked)';
+}
+export async function runMatrixInit(io, flags) {
+    return runCommand('matrix init', io, flags, async (ctx) => {
+        let payload;
+        try {
+            payload = await ctx.client.post(`/v1/tracks/${encodeURIComponent(ctx.project)}/${encodeURIComponent(flags.track)}/matrix`, flags.force ? { force: true } : {});
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.code === 'conflict') {
+                throw new CommandError(`${explain(err, ctx.ctx)} — ${FORCE_HINT}`);
+            }
+            throw err;
+        }
+        if (flags.json)
+            return jsonResult(payload);
+        const view = asRecord(payload);
+        const added = new Set(asArray(view.added).map((id) => text(id, '')));
+        const rows = asArray(view.rows).map((row) => asRecord(row));
+        const lines = [];
+        for (const row of rows) {
+            const id = text(row.row_id, '');
+            if (!added.has(id))
+                continue;
+            lines.push(`${pad(id, 22)}${pad(criterionLabel(row.linked_criterion), 16)}${text(row.what_to_verify, '(no description)')}`);
+        }
+        if (added.size === 0) {
+            lines.push('no rows added — every criterion on this track already has one');
+        }
+        const gate = asRecord(view.gate);
+        const blocking = asArray(gate.blocking).length;
+        lines.push(`${plural(added.size, 'row')} added; ${plural(rows.length, 'row')} on ${flags.track}; gate: ${gate.ok === true ? 'ok' : `blocked (${blocking} blocking)`}`);
+        return { ok: true, lines };
+    });
+}
+//# sourceMappingURL=matrix.js.map

package/dist/commands/matrix.js.map

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

package/dist/commands/next.d.ts

@@ -0,0 +1,14 @@
+import type { TargetFlags } from '../config.js';
+import { type CommandIo, type CommandResult } from './common.js';
+/**
+ * `backlog next` — what is ready to pick up, in the order core ranked it. No cache: "what
+ * should I do next" read from a stale file is how two people take the same item.
+ *
+ * The `warnings[]` the op returns are prerequisites naming refs the project does not hold;
+ * core cannot tell a typo from an unfiled item, so it stays silent and the caller is told.
+ */
+export interface NextFlags extends TargetFlags {
+    limit?: number | undefined;
+    json?: boolean | undefined;
+}
+export declare function runNext(io: CommandIo, flags: NextFlags): Promise<CommandResult>;