@shrkcrft/cli 0.1.0-alpha.2

package/dist/output/failure-hints.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Centralised failure-to-success hint formatter.
+ *
+ * Keeps the "next command" message consistent across high-friction
+ * commands. Each helper emits a compact one-paragraph "Next commands"
+ * block on stdout.
+ */
+export interface IFailureHint {
+    label: string;
+    command: string;
+    /** Optional doc link. */
+    doc?: string;
+}
+export declare function renderFailureHints(hints: readonly IFailureHint[]): string;
+export declare function doctorHints(): IFailureHint[];
+export declare function staleKnowledgeHints(): IFailureHint[];
+export declare function templateDriftHints(): IFailureHint[];
+export declare function fuzzyImpactAmbiguousHints(): IFailureHint[];
+export declare function agentTestMissingExpectedHints(): IFailureHint[];
+export declare function ciReportEmptyHints(): IFailureHint[];
+export declare function feedbackRulesDoctorHints(): IFailureHint[];
+/**
+ * Standardised error footer for important failures.
+ *
+ *   Next:
+ *     <command>
+ *
+ *   Why:
+ *     <one sentence>
+ *
+ *   More detail (optional):
+ *     <command>
+ *
+ * Centralized so unknown-command / ambiguous-command / apply-rejected /
+ * signature-mismatch / contract-gate-blocked / folder-op-unsafe /
+ * doctor-failed / self-config-doctor-failed / stale-pack-signature /
+ * project-coupling-audit / templates-drift / knowledge-stale-check all
+ * read the same way.
+ */
+export interface IErrorFooter {
+    next: string;
+    why: string;
+    more?: string | readonly string[];
+}
+export declare function renderErrorFooter(footer: IErrorFooter): string;
+export type ErrorFooterKind = 'unknown-command' | 'ambiguous-command' | 'apply-rejected' | 'signature-mismatch' | 'contract-gate-blocked' | 'folder-op-unsafe' | 'doctor-failed' | 'self-config-doctor-failed' | 'stale-pack-signature' | 'project-coupling-audit-failed' | 'templates-drift-failed' | 'knowledge-stale-check-failed';
+/**
+ * Canonical footer per failure kind. Returns `undefined` if the
+ * caller wants to fall through to a bespoke message (we don't crash if
+ * a new kind is added without a wired footer).
+ */
+export declare function errorFooterFor(kind: ErrorFooterKind, context?: {
+    task?: string;
+}): IErrorFooter | undefined;
+//# sourceMappingURL=failure-hints.d.ts.map

package/dist/output/failure-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-hints.d.ts","sourceRoot":"","sources":["../../src/output/failure-hints.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAUzE;AAID,wBAAgB,WAAW,IAAI,YAAY,EAAE,CAM5C;AAED,wBAAgB,mBAAmB,IAAI,YAAY,EAAE,CAMpD;AAED,wBAAgB,kBAAkB,IAAI,YAAY,EAAE,CAMnD;AAED,wBAAgB,yBAAyB,IAAI,YAAY,EAAE,CAK1D;AAED,wBAAgB,6BAA6B,IAAI,YAAY,EAAE,CAK9D;AAED,wBAAgB,kBAAkB,IAAI,YAAY,EAAE,CAKnD;AAED,wBAAgB,wBAAwB,IAAI,YAAY,EAAE,CAKzD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAiB9D;AAED,MAAM,MAAM,eAAe,GACvB,iBAAiB,GACjB,mBAAmB,GACnB,gBAAgB,GAChB,oBAAoB,GACpB,uBAAuB,GACvB,kBAAkB,GAClB,eAAe,GACf,2BAA2B,GAC3B,sBAAsB,GACtB,+BAA+B,GAC/B,wBAAwB,GACxB,8BAA8B,CAAC;AAEnC;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,YAAY,GAAG,SAAS,CA4E3G"}

package/dist/output/failure-hints.js

@@ -0,0 +1,159 @@
+export function renderFailureHints(hints) {
+    if (hints.length === 0)
+        return '';
+    const lines = [];
+    lines.push('');
+    lines.push('Next commands:');
+    for (const h of hints) {
+        lines.push(`  $ ${h.command}   # ${h.label}`);
+        if (h.doc)
+            lines.push(`     docs: ${h.doc}`);
+    }
+    return lines.join('\n') + '\n';
+}
+// ── Convenience hint builders ──────────────────────────────────────────
+export function doctorHints() {
+    return [
+        { label: 'preview fix suggestions', command: 'shrk fix preview --action-hints' },
+        { label: 'list suppressions', command: 'shrk doctor suppressions list' },
+        { label: 'watch loop', command: 'shrk doctor --watch --once' },
+    ];
+}
+export function staleKnowledgeHints() {
+    return [
+        { label: 'preview rename', command: 'shrk knowledge rename-symbol <old> <new> --dry-run' },
+        { label: 'list references', command: 'shrk knowledge references <id>' },
+        { label: 'fix preview', command: 'shrk fix preview --knowledge-stale' },
+    ];
+}
+export function templateDriftHints() {
+    return [
+        { label: 'fix preview', command: 'shrk fix preview --template-drift' },
+        { label: 'inspect template', command: 'shrk templates get <id>' },
+        { label: 'verify paths', command: 'shrk templates verify-paths' },
+    ];
+}
+export function fuzzyImpactAmbiguousHints() {
+    return [
+        { label: 'resolve only', command: 'shrk impact <query> --resolve-only' },
+        { label: 'trace alternatives', command: 'shrk trace <query>' },
+    ];
+}
+export function agentTestMissingExpectedHints() {
+    return [
+        { label: 'explain a missing id', command: 'shrk why <id> --for-task "<task>"' },
+        { label: 'explain why not', command: 'shrk why-not <id> --for-task "<task>"' },
+    ];
+}
+export function ciReportEmptyHints() {
+    return [
+        { label: 'scaffold integrity gates', command: 'shrk ci scaffold github-actions --with-integrity' },
+        { label: 'run gates locally', command: 'shrk quality --ci' },
+    ];
+}
+export function feedbackRulesDoctorHints() {
+    return [
+        { label: 'list rules', command: 'shrk feedback rules list --with-pack-rules' },
+        { label: 'ingest sample', command: 'shrk feedback ingest <file> --with-pack-rules' },
+    ];
+}
+export function renderErrorFooter(footer) {
+    const lines = [];
+    lines.push('');
+    lines.push('Next:');
+    lines.push(`  $ ${footer.next}`);
+    lines.push('');
+    lines.push('Why:');
+    lines.push(`  ${footer.why}`);
+    if (footer.more) {
+        lines.push('');
+        lines.push('More detail:');
+        const moreCommands = typeof footer.more === 'string' ? [footer.more] : footer.more;
+        for (const cmd of moreCommands) {
+            lines.push(`  $ ${cmd}`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+/**
+ * Canonical footer per failure kind. Returns `undefined` if the
+ * caller wants to fall through to a bespoke message (we don't crash if
+ * a new kind is added without a wired footer).
+ */
+export function errorFooterFor(kind, context) {
+    const task = context?.task ?? '<task>';
+    switch (kind) {
+        case 'unknown-command':
+            return {
+                next: `shrk recommend "${task}"`,
+                why: 'Free-form input routes to the canonical human entrypoint — `shrk recommend` ranks commands for a query without writes.',
+                more: ['shrk commands', 'shrk commands suggest "<partial>"', 'shrk start-here'],
+            };
+        case 'ambiguous-command':
+            return {
+                next: 'shrk commands suggest "<partial>"',
+                why: 'Multiple commands matched the input — narrow it down or pick the canonical entrypoint.',
+                more: ['shrk commands explain <cmd>', 'shrk commands overlaps'],
+            };
+        case 'apply-rejected':
+            return {
+                next: 'shrk plan review <plan.json>',
+                why: 'The apply gate refused the plan — review the safety report before retrying.',
+                more: ['shrk plan verify <plan.json>', 'shrk safety audit --deep'],
+            };
+        case 'signature-mismatch':
+            return {
+                next: 'shrk plan verify <plan.json>',
+                why: 'The plan signature does not match the source content — re-sign or regenerate before retrying.',
+                more: ['shrk plan sign <plan.json>', 'shrk gen <template> --save-plan <plan.json>'],
+            };
+        case 'contract-gate-blocked':
+            return {
+                next: 'shrk contract status <id>',
+                why: 'The contract gate refused the apply — inspect the contract before approving.',
+                more: ['shrk contract check <id>', 'shrk contract approve <id>'],
+            };
+        case 'folder-op-unsafe':
+            return {
+                next: 'shrk plan review <plan.json>',
+                why: 'The plan touches files outside the project scope — review before applying.',
+                more: ['shrk safety audit --deep', 'shrk check boundaries --changed-only'],
+            };
+        case 'doctor-failed':
+            return {
+                next: 'shrk doctor',
+                why: 'Workspace doctor reported errors — fix or suppress them before continuing.',
+                more: ['shrk doctor suppressions list', 'shrk fix preview --action-hints', 'shrk self-config doctor'],
+            };
+        case 'self-config-doctor-failed':
+            return {
+                next: 'shrk self-config doctor',
+                why: 'The cross-reference doctor reported issues — fix the contributions or rebuild the graph.',
+                more: ['shrk packs doctor --require-signatures', 'shrk self-config graph'],
+            };
+        case 'stale-pack-signature':
+            return {
+                next: 'shrk packs sign <pack>',
+                why: 'A pack manifest changed after it was signed — re-sign to restore the trust chain.',
+                more: ['shrk packs verify <pack>', 'shrk packs signature-status'],
+            };
+        case 'project-coupling-audit-failed':
+            return {
+                next: 'shrk audit project-coupling audit --token "<token>" --fail-on engine',
+                why: 'Project-specific tokens leaked into the SharkCraft engine — move them into the appropriate pack.',
+                more: ['shrk impact --files "<file>"', 'shrk explore packages/<pkg>'],
+            };
+        case 'templates-drift-failed':
+            return {
+                next: 'shrk templates drift --min-severity warning',
+                why: 'A template body diverged from its declared shape — regenerate or update the template.',
+                more: ['shrk fix preview --template-drift', 'shrk templates verify-paths'],
+            };
+        case 'knowledge-stale-check-failed':
+            return {
+                next: 'shrk knowledge stale-check --ci',
+                why: 'A knowledge anchor moved or vanished — refresh the anchor or remove the entry.',
+                more: ['shrk fix preview --knowledge-stale', 'shrk knowledge references <id>'],
+            };
+    }
+}

package/dist/output/format-output.d.ts

@@ -0,0 +1,9 @@
+export declare function header(text: string): string;
+export declare function bullet(text: string): string;
+export declare function kv(key: string, value: string | number | boolean | undefined | null): string;
+export declare function asJson(value: unknown): string;
+export declare function table(rows: readonly (readonly string[])[]): string;
+export interface PrintOptions {
+    json?: boolean;
+}
+//# sourceMappingURL=format-output.d.ts.map

package/dist/output/format-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-output.d.ts","sourceRoot":"","sources":["../../src/output/format-output.ts"],"names":[],"mappings":"AAAA,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,wBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAG3F;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE7C;AAED,wBAAgB,KAAK,CAAC,IAAI,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,GAAG,MAAM,CAWlE;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB"}

package/dist/output/format-output.js

@@ -0,0 +1,26 @@
+export function header(text) {
+    return `\n=== ${text} ===\n`;
+}
+export function bullet(text) {
+    return `  • ${text}`;
+}
+export function kv(key, value) {
+    const v = value === undefined || value === null ? '(none)' : String(value);
+    return `  ${key.padEnd(18)} ${v}`;
+}
+export function asJson(value) {
+    return JSON.stringify(value, null, 2);
+}
+export function table(rows) {
+    if (rows.length === 0)
+        return '';
+    const widths = [];
+    for (const row of rows) {
+        for (let i = 0; i < row.length; i += 1) {
+            widths[i] = Math.max(widths[i] ?? 0, (row[i] ?? '').length);
+        }
+    }
+    return rows
+        .map((row) => row.map((cell, i) => (cell ?? '').padEnd(widths[i] ?? 0)).join('  ').trimEnd())
+        .join('\n');
+}

package/dist/output/print-error.d.ts

@@ -0,0 +1,3 @@
+import type { AppError } from '@shrkcrft/core';
+export declare function printError(error: AppError | Error): void;
+//# sourceMappingURL=print-error.d.ts.map

package/dist/output/print-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"print-error.d.ts","sourceRoot":"","sources":["../../src/output/print-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,wBAAgB,UAAU,CAAC,KAAK,EAAE,QAAQ,GAAG,KAAK,GAAG,IAAI,CAWxD"}

package/dist/output/print-error.js

@@ -0,0 +1,14 @@
+export function printError(error) {
+    if ('code' in error) {
+        const ae = error;
+        process.stderr.write(`Error [${ae.code}]: ${ae.message}\n`);
+        if (ae.suggestion)
+            process.stderr.write(`  hint: ${ae.suggestion}\n`);
+        if (ae.details && Object.keys(ae.details).length) {
+            process.stderr.write(`  details: ${JSON.stringify(ae.details)}\n`);
+        }
+    }
+    else {
+        process.stderr.write(`Error: ${error.message}\n`);
+    }
+}

package/dist/output/watch-loop.d.ts

@@ -0,0 +1,37 @@
+export interface IWatchLoopOptions {
+    cwd: string;
+    /** Run a single iteration and exit. */
+    once?: boolean;
+    /** Debounce delay (ms). Default 300. */
+    debounce?: number;
+    /** Extra paths to watch (relative to cwd). Defaults to `sharkcraft/`. */
+    paths?: readonly string[];
+}
+export interface IWatchLoopHandlers {
+    /** Produce one snapshot. */
+    snapshot(): Promise<void>;
+    /** Optional cleanup. */
+    shutdown?: () => Promise<void> | void;
+}
+export declare function runWatchLoop(options: IWatchLoopOptions, handlers: IWatchLoopHandlers): Promise<number>;
+/**
+ * Build a "plan" describing what a watch loop would do — used by MCP / tests
+ * to verify watch wiring without keeping a process open.
+ */
+export interface IWatchPlan {
+    schema: 'sharkcraft.watch-plan/v1';
+    cwd: string;
+    debounce: number;
+    paths: readonly string[];
+    steps: readonly string[];
+}
+export declare function buildWatchPlan(options: IWatchLoopOptions, steps: readonly string[]): IWatchPlan;
+import type { ParsedArgs } from '../command-registry.js';
+/**
+ * Run a command's `run` function inside a watch loop when --watch is set.
+ *
+ * @returns null if --watch is not set (caller proceeds as before), otherwise
+ * the exit code of the watch loop.
+ */
+export declare function maybeRunInWatchMode(args: ParsedArgs, runner: (innerArgs: ParsedArgs) => Promise<number>): Promise<number | null>;
+//# sourceMappingURL=watch-loop.d.ts.map

package/dist/output/watch-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-loop.d.ts","sourceRoot":"","sources":["../../src/output/watch-loop.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,4BAA4B;IAC5B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACvC;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,iBAAiB,EAC1B,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,MAAM,CAAC,CA6DjB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,0BAA0B,CAAC;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,wBAAgB,cAAc,CAC5B,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,UAAU,CAYZ;AAED,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGzD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,CAAC,SAAS,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,GACjD,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA0BxB"}

package/dist/output/watch-loop.js

@@ -0,0 +1,115 @@
+/**
+ * Lightweight watch loop helper.
+ *
+ * Reused by doctor / knowledge stale-check / templates drift / test agent /
+ * `shrk watch integrity`. Debounces fs change events, runs the supplied
+ * snapshot once at startup, and short-circuits when --once is passed.
+ *
+ * Linux: falls back to a non-recursive watcher when `recursive: true` throws.
+ */
+import { existsSync, watch as fsWatch } from 'node:fs';
+import * as nodePath from 'node:path';
+export async function runWatchLoop(options, handlers) {
+    const cwd = options.cwd;
+    const debounce = options.debounce ?? 300;
+    const watchPaths = (options.paths && options.paths.length > 0
+        ? options.paths
+        : ['sharkcraft']).map((p) => (nodePath.isAbsolute(p) ? p : nodePath.join(cwd, p)));
+    // Initial snapshot.
+    await handlers.snapshot();
+    if (options.once) {
+        if (handlers.shutdown)
+            await handlers.shutdown();
+        return 0;
+    }
+    const existing = watchPaths.filter((p) => existsSync(p));
+    if (existing.length === 0) {
+        process.stderr.write(`[watch] no watchable paths under ${cwd}. Add sharkcraft/ or pass --paths.\n`);
+        if (handlers.shutdown)
+            await handlers.shutdown();
+        return 1;
+    }
+    process.stdout.write('\n[watch] running — Ctrl-C to stop.\n');
+    let timer;
+    const schedule = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(async () => {
+            try {
+                await handlers.snapshot();
+            }
+            catch (e) {
+                process.stderr.write(`[watch] error: ${e.message}\n`);
+            }
+        }, debounce);
+    };
+    const watchers = [];
+    for (const p of existing) {
+        try {
+            watchers.push(fsWatch(p, { recursive: true }, () => schedule()));
+        }
+        catch {
+            // Linux fallback — non-recursive top-level watch.
+            watchers.push(fsWatch(p, () => schedule()));
+        }
+    }
+    return new Promise((resolve) => {
+        process.on('SIGINT', () => {
+            for (const w of watchers)
+                w.close();
+            if (handlers.shutdown)
+                Promise.resolve(handlers.shutdown()).finally(() => {
+                    process.stdout.write('\n[watch] stopped.\n');
+                    resolve(0);
+                });
+            else {
+                process.stdout.write('\n[watch] stopped.\n');
+                resolve(0);
+            }
+        });
+    });
+}
+export function buildWatchPlan(options, steps) {
+    const watchPaths = (options.paths && options.paths.length > 0
+        ? options.paths
+        : ['sharkcraft']);
+    return {
+        schema: 'sharkcraft.watch-plan/v1',
+        cwd: options.cwd,
+        debounce: options.debounce ?? 300,
+        paths: watchPaths,
+        steps,
+    };
+}
+import { flagBool, flagNumber, resolveCwd } from "../command-registry.js";
+/**
+ * Run a command's `run` function inside a watch loop when --watch is set.
+ *
+ * @returns null if --watch is not set (caller proceeds as before), otherwise
+ * the exit code of the watch loop.
+ */
+export async function maybeRunInWatchMode(args, runner) {
+    if (!flagBool(args, 'watch'))
+        return null;
+    const cwd = resolveCwd(args);
+    const debounce = flagNumber(args, 'debounce') ?? 300;
+    const once = flagBool(args, 'once');
+    // Strip --watch so the inner snapshot doesn't recurse.
+    const innerFlags = new Map(args.flags);
+    innerFlags.delete('watch');
+    innerFlags.delete('once');
+    innerFlags.delete('debounce');
+    const innerArgs = {
+        positional: args.positional,
+        flags: innerFlags,
+        multiFlags: args.multiFlags,
+        ...(args.globalCwd ? { globalCwd: args.globalCwd } : {}),
+    };
+    return runWatchLoop({ cwd, debounce, once }, {
+        snapshot: async () => {
+            const ts = new Date().toLocaleTimeString();
+            process.stdout.write(`\n[watch] ${ts}\n`);
+            await runner(innerArgs);
+        },
+    });
+}