@shrkcrft/cli 0.1.0-alpha.2 → 0.1.0-alpha.20

package/dist/audit/templates-fix-plan.js

@@ -0,0 +1,174 @@
+const TEMPLATES_FILE = 'sharkcraft/templates.ts';
+export function buildFixPlan(report) {
+    const fixes = [];
+    const skipped = [];
+    for (const entry of report.templates) {
+        for (const f of entry.deterministicFindings) {
+            const out = dispatchDeterministic(entry, f);
+            if (out.kind === 'fix')
+                fixes.push(out.fix);
+            else
+                skipped.push(out.skip);
+        }
+        for (const f of entry.llmFindings) {
+            fixes.push(makeLlmFix(entry, f));
+        }
+    }
+    const summary = {
+        fixCount: fixes.length,
+        highConfidence: fixes.filter((f) => f.confidence === 'high').length,
+        mediumConfidence: fixes.filter((f) => f.confidence === 'medium').length,
+        lowConfidence: fixes.filter((f) => f.confidence === 'low').length,
+        skipped: skipped.length,
+    };
+    const generatedAt = new Date().toISOString();
+    return {
+        fixPlanId: `fix-${generatedAt.replace(/[:.]/g, '-')}`,
+        generatedAt,
+        auditId: report.auditId,
+        sourceFiles: [TEMPLATES_FILE],
+        fixes,
+        skipped,
+        summary,
+    };
+}
+function dispatchDeterministic(entry, f) {
+    switch (f.category) {
+        case 'unsafe-target':
+            return {
+                kind: 'skip',
+                skip: {
+                    templateId: entry.templateId,
+                    findingCategory: f.category,
+                    finding: f.message,
+                    reason: 'security-sensitive — requires human review',
+                },
+            };
+        case 'missing-name':
+            return makeFix(entry, f, 'high', 'Add a `name` field to this template.', [
+                `Open ${TEMPLATES_FILE}. Find the template literal with id "${entry.templateId}".`,
+                `Add a \`name: '<human-readable name>'\` field next to \`id\`.`,
+                `The name should briefly describe what the template scaffolds (e.g. "CLI command (shrk subcommand)").`,
+                `Do not change other fields. Verify the file still parses.`,
+            ].join('\n'));
+        case 'missing-description':
+            return makeFix(entry, f, 'high', 'Add a `description` field to this template.', [
+                `Open ${TEMPLATES_FILE}. Find the template literal with id "${entry.templateId}".`,
+                `Add a \`description: '<one-sentence description>'\` field. The description appears in \`shrk templates list\` and should explain what the template generates.`,
+                `Do not change other fields. Verify the file still parses.`,
+            ].join('\n'));
+        case 'related-id-unresolved': {
+            const id = extractQuoted(f.message);
+            if (!id) {
+                return makeFix(entry, f, 'medium', 'Remove an unresolved related id (id could not be auto-extracted from the message).', [
+                    `Open ${TEMPLATES_FILE}. Find the template literal with id "${entry.templateId}".`,
+                    `The finding is: "${f.message}"`,
+                    `Remove the unresolved related id from the \`related\` array. Do not invent a replacement; if no real id applies, leave the array empty or omit the field.`,
+                    `Verify the file still parses.`,
+                ].join('\n'));
+            }
+            return makeFix(entry, f, 'high', `Remove "${id}" from the \`related\` array.`, [
+                `Open ${TEMPLATES_FILE}. Find the template literal with id "${entry.templateId}".`,
+                `In its \`related\` array, remove the string "${id}". Do not change any other entries.`,
+                `Verify the file still parses and that "${id}" is not referenced elsewhere in the file.`,
+            ].join('\n'));
+        }
+        case 'undocumented-var': {
+            const varName = extractQuoted(f.message);
+            const where = varName ? `the variable named "${varName}"` : 'the variable referenced in the finding';
+            return makeFix(entry, f, 'medium', varName
+                ? `Add a description to variable "${varName}".`
+                : 'Add a description to an undocumented variable.', [
+                `Open ${TEMPLATES_FILE}. Find the template literal with id "${entry.templateId}".`,
+                `Locate ${where} inside the \`variables\` array.`,
+                `Add a \`description: '<short explanation>'\` field. The description should explain what the variable controls and where its value ends up in the generated output.`,
+                `Verify the file still parses.`,
+            ].join('\n'));
+        }
+        case 'required-var-no-example': {
+            const varName = extractQuoted(f.message);
+            const where = varName ? `the variable named "${varName}"` : 'the required variable referenced in the finding';
+            return makeFix(entry, f, 'medium', varName
+                ? `Add an example value to required variable "${varName}".`
+                : 'Add an example value to a required variable that lacks one.', [
+                `Open ${TEMPLATES_FILE}. Find the template literal with id "${entry.templateId}".`,
+                `Locate ${where} inside the \`variables\` array.`,
+                `Add an \`examples: ['<sample value>']\` field. Choose a sample that's representative of real usage — readable by humans, valid against any \`pattern\` that may also be defined.`,
+                `Verify the file still parses.`,
+            ].join('\n'));
+        }
+        case 'undeclared-var': {
+            const varName = extractPlaceholder(f.message);
+            const where = varName ? `\`{{${varName}}}\`` : 'the undeclared placeholder named in the finding';
+            return makeFix(entry, f, 'medium', varName
+                ? `Resolve undeclared placeholder ${where}.`
+                : 'Resolve an undeclared placeholder in the template body.', [
+                `Open ${TEMPLATES_FILE}. Find the template literal with id "${entry.templateId}".`,
+                `The template body uses placeholder ${where} that isn't declared in \`variables[]\`.`,
+                `Pick one:`,
+                `  (a) Add a corresponding entry to \`variables[]\` (with \`name\`, \`required\`, and ideally a \`description\` + \`examples\`). This is right if the placeholder represents intended user input.`,
+                `  (b) Remove the placeholder from the template body. This is right if it was a typo or leftover.`,
+                `Choose based on what the surrounding body and template description imply. Verify the file still parses.`,
+            ].join('\n'));
+        }
+        case 'path-no-convention': {
+            const samplePath = extractQuoted(f.message);
+            return makeFix(entry, f, 'low', samplePath
+                ? `Align template targetPath with path conventions (sample: "${samplePath}").`
+                : 'Align template targetPath with path conventions.', [
+                `The sample target path${samplePath ? ` "${samplePath}"` : ''} doesn't match any entry in \`sharkcraft/paths.ts\`.`,
+                `Decide between two fixes:`,
+                `  (a) Update the template's \`targetPath\` so its rendered output matches an existing path convention. Edit ${TEMPLATES_FILE}, find template "${entry.templateId}", and adjust its \`targetPath\` function/string.`,
+                `  (b) Add a matching entry to \`sharkcraft/paths.ts\` if this template's output really does belong in a new location.`,
+                `Prefer (a) unless the template represents a genuinely new file-shape for the project. Verify both files parse.`,
+            ].join('\n'));
+        }
+        default:
+            return makeFix(entry, f, 'low', `Address finding "${f.category}".`, [
+                `Open ${TEMPLATES_FILE}. Find the template literal with id "${entry.templateId}".`,
+                `The audit reported: ${f.message}`,
+                f.suggestion ? `Suggested fix from the inspector: ${f.suggestion}` : 'No specific suggestion was supplied — use judgment.',
+                `Apply a minimal change that resolves the finding without touching unrelated fields. Verify the file still parses.`,
+            ].filter(Boolean).join('\n'));
+    }
+}
+function makeFix(entry, f, confidence, intent, agentPrompt) {
+    return {
+        kind: 'fix',
+        fix: {
+            templateId: entry.templateId,
+            findingCategory: f.category,
+            finding: f.message,
+            severity: f.severity,
+            intent,
+            agentPrompt,
+            confidence,
+            source: 'deterministic',
+        },
+    };
+}
+function makeLlmFix(entry, f) {
+    return {
+        templateId: entry.templateId,
+        findingCategory: f.category,
+        finding: f.message,
+        severity: f.severity,
+        intent: `Review the LLM-flagged "${f.category}" finding and decide whether to act.`,
+        agentPrompt: [
+            `Open ${TEMPLATES_FILE}. Find the template literal with id "${entry.templateId}".`,
+            `An LLM critique flagged (confidence ${f.confidence.toFixed(2)}): ${f.message}`,
+            `LLM findings are advisory — verify against the template body and sibling templates before acting.`,
+            `If you choose to act, keep the change minimal and scoped to the finding. If you don't, that's also a valid outcome — record the decision in your response.`,
+        ].join('\n'),
+        confidence: 'low',
+        source: 'llm',
+    };
+}
+function extractQuoted(message) {
+    const m = message.match(/"([^"]+)"/);
+    return m ? m[1] : null;
+}
+function extractPlaceholder(message) {
+    const m = message.match(/\{\{\s*([A-Za-z_$][A-Za-z0-9_$]*)\s*\}\}/);
+    return m ? m[1] : null;
+}

package/dist/command-registry.d.ts

@@ -10,6 +10,14 @@ export interface ICommandHandler {
     name: string;
     description: string;
     usage: string;
+    /**
+     * Flags that take NO value (e.g. `json`, `no-enhance`). Listed here so the
+     * parser doesn't greedily swallow the following token as the flag's value —
+     * `compress --json <file>` / `smart-context --no-enhance "<task>"` keep the
+     * token as a positional regardless of argument order (the order an LLM
+     * naturally emits). Optional; commands without it parse exactly as before.
+     */
+    booleanFlags?: ReadonlySet<string>;
     run(args: ParsedArgs): Promise<number> | number;
 }
 /**
@@ -101,6 +109,8 @@ export declare class CommandRegistry {
 export interface ParseArgsOptions {
     /** Global cwd resolved during pre-parse, propagated to the command. */
     globalCwd?: string;
+    /** Flags that take no value — they never consume the following token. */
+    booleanFlags?: ReadonlySet<string>;
 }
 export declare function parseArgs(argv: readonly string[], options?: ParseArgsOptions): ParsedArgs;
 /**
@@ -111,6 +121,24 @@ export declare function extractGlobalCwd(argv: readonly string[]): {
     cwd?: string;
     rest: string[];
 };
+/** A request to compress a command's stdout, parsed from the global flags. */
+export interface IGlobalCompressDirective {
+    /** Force a content type for the compressor (else auto-detect). */
+    type?: string;
+    /** Query text that biases which lines/matches the compressor keeps. */
+    query?: string;
+}
+/**
+ * Extracts the global output-compression flags from anywhere in argv:
+ * `--compress` / `--ccr` (synonyms; turn it on) plus optional
+ * `--compress-type <t>` and `--compress-query <q>`. Returns the directive (when
+ * any was present) and the remaining argv with those flags removed — so the
+ * underlying command can be re-run cleanly without them (and never recurses).
+ */
+export declare function extractGlobalCompress(argv: readonly string[]): {
+    directive?: IGlobalCompressDirective;
+    rest: string[];
+};
 /**
  * Returns the absolute cwd for the current command:
  * 1. Command-level --cwd flag (if passed after the command)

package/dist/command-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-registry.d.ts","sourceRoot":"","sources":["../src/command-registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"command-registry.d.ts","sourceRoot":"","sources":["../src/command-registry.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IACrC,0EAA0E;IAC1E,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAClC,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC,GAAG,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;CACjD;AAED;;;;;GAKG;AACH,UAAU,gBAAgB;IACxB,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAMD,mDAAmD;AACnD,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,sEAAsE;IACtE,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,6EAA6E;IAC7E,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoC;IACzD,uFAAuF;IACvF,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAC1D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAE5D,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAIxC,0DAA0D;IAC1D,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI;IAIjE;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI;IAgBnE,qCAAqC;IACrC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAKlD,uCAAuC;IACvC,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAKpD,iEAAiE;IACjE,OAAO,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAa9E,gCAAgC;IAChC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAK9C,8BAA8B;IAC9B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAOhE,8DAA8D;IAC9D,KAAK,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,eAAe,GAAG,SAAS;IAK3D,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAInC,UAAU,IAAI,SAAS,MAAM,EAAE;IAW/B,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,eAAe,EAAE;IAWpD,2EAA2E;IAC3E,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE;IAUzD,gBAAgB,IAAI,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC;IAI/C,kBAAkB,IAAI,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC;IAIjD,gDAAgD;IAChD,IAAI,IAAI,SAAS,eAAe,EAAE;IAQlC,oDAAoD;IACpD,OAAO,IAAI,aAAa,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;KAAE,CAAC;IAMjG;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB;IAsBtD,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,UAAU;CAWnB;AAQD,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACpC;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,gBAAqB,GAAG,UAAU,CA6C7F;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CA+BA;AAED,8EAA8E;AAC9E,MAAM,WAAW,wBAAwB;IACvC,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IAC9D,SAAS,CAAC,EAAE,wBAAwB,CAAC;IACrC,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAkEA;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAKnD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG7E;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAGhE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK7E;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;CACrC;AAED,wBAAgB,QAAQ,CACtB,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,gBAAqB,GAC7B,MAAM,EAAE,CAkCV;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQjE"}

package/dist/command-registry.js

@@ -222,7 +222,13 @@ export function parseArgs(argv, options = {}) {
             else {
                 key = arg.slice(2);
                 const next = argv[i + 1];
-                if (next !== undefined && !next.startsWith('-')) {
+                // A known boolean flag never consumes the following token, so
+                // flag-first ordering (`--json <file>`, `--no-enhance "<task>"`) keeps
+                // the token as a positional instead of swallowing it as the value.
+                if (options.booleanFlags?.has(key)) {
+                    value = true;
+                }
+                else if (next !== undefined && !next.startsWith('-')) {
                     value = next;
                     i += 1;
                 }
@@ -256,6 +262,13 @@ export function extractGlobalCwd(argv) {
     let cwd;
     for (let i = 0; i < argv.length; i += 1) {
         const t = argv[i];
+        // Honor the POSIX `--` end-of-options separator (as parseArgs does):
+        // everything after it is a literal positional, so a `--cwd` there must not
+        // be intercepted. Preserve `--` and the remainder verbatim.
+        if (t === '--') {
+            rest.push(...argv.slice(i));
+            break;
+        }
         if (t === '--cwd') {
             const next = argv[i + 1];
             if (next !== undefined && !next.startsWith('-')) {
@@ -277,6 +290,83 @@ export function extractGlobalCwd(argv) {
         cwd = nodePath.resolve(process.cwd(), cwd);
     return cwd === undefined ? { rest } : { cwd, rest };
 }
+/**
+ * Extracts the global output-compression flags from anywhere in argv:
+ * `--compress` / `--ccr` (synonyms; turn it on) plus optional
+ * `--compress-type <t>` and `--compress-query <q>`. Returns the directive (when
+ * any was present) and the remaining argv with those flags removed — so the
+ * underlying command can be re-run cleanly without them (and never recurses).
+ */
+export function extractGlobalCompress(argv) {
+    const rest = [];
+    let active = false;
+    let type;
+    let query;
+    const valued = (token, flag, set, i) => {
+        if (token === flag) {
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('-')) {
+                set(next);
+                return true; // caller skips next
+            }
+            return false;
+        }
+        return false;
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const t = argv[i];
+        // Honor the POSIX `--` end-of-options separator exactly as parseArgs does:
+        // everything after it is a literal positional, so a compress-flag-shaped
+        // token there must NOT be intercepted (and the next token must not be
+        // swallowed as a value). Preserve `--` and the remainder verbatim for the
+        // child to re-parse.
+        if (t === '--') {
+            rest.push(...argv.slice(i));
+            break;
+        }
+        if (t === '--compress' || t === '--ccr') {
+            active = true;
+            continue;
+        }
+        if (t.startsWith('--compress-type=')) {
+            type = t.slice('--compress-type='.length);
+            active = true;
+            continue;
+        }
+        if (t.startsWith('--compress-query=')) {
+            query = t.slice('--compress-query='.length);
+            active = true;
+            continue;
+        }
+        if (t === '--compress-type') {
+            if (valued(t, '--compress-type', (v) => (type = v), i)) {
+                active = true;
+                i += 1;
+                continue;
+            }
+            active = true;
+            continue;
+        }
+        if (t === '--compress-query') {
+            if (valued(t, '--compress-query', (v) => (query = v), i)) {
+                active = true;
+                i += 1;
+                continue;
+            }
+            active = true;
+            continue;
+        }
+        rest.push(t);
+    }
+    if (!active)
+        return { rest };
+    const directive = {};
+    if (type !== undefined)
+        directive.type = type;
+    if (query !== undefined)
+        directive.query = query;
+    return { directive, rest };
+}
 /**
  * Returns the absolute cwd for the current command:
  * 1. Command-level --cwd flag (if passed after the command)

package/dist/commands/ai-status.command.d.ts

@@ -0,0 +1,19 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk ai-status` — one-shot self-check of the LLM wiring.
+ *
+ * Designed for agents (like Claude) that want to know whether shrk's
+ * LLM enrichment is going to do anything useful, without having to
+ * run a full audit. Three pieces of information:
+ *   1. Which provider, if any, the local-first walk would pick.
+ *   2. The structured `ai` block (the same one every audit emits) so
+ *      the agent can act on the hints.
+ *   3. Optional `--ping`: a tiny live request that proves the
+ *      provider really responds (the resolver only checks env vars).
+ *
+ * The deterministic baseline contract: works without LLM. With no
+ * provider reachable, the output is still useful — it carries the
+ * setup hints.
+ */
+export declare const aiStatusCommand: ICommandHandler;
+//# sourceMappingURL=ai-status.command.d.ts.map

package/dist/commands/ai-status.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-status.command.d.ts","sourceRoot":"","sources":["../../src/commands/ai-status.command.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,EAAE,eAkD7B,CAAC"}

package/dist/commands/ai-status.command.js

@@ -0,0 +1,94 @@
+import { AiMessageRole, buildAiBlock, renderAiBlockMarkdown, selectAiProvider, } from '@shrkcrft/ai';
+import { flagBool, flagNumber, flagString, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+/**
+ * `shrk ai-status` — one-shot self-check of the LLM wiring.
+ *
+ * Designed for agents (like Claude) that want to know whether shrk's
+ * LLM enrichment is going to do anything useful, without having to
+ * run a full audit. Three pieces of information:
+ *   1. Which provider, if any, the local-first walk would pick.
+ *   2. The structured `ai` block (the same one every audit emits) so
+ *      the agent can act on the hints.
+ *   3. Optional `--ping`: a tiny live request that proves the
+ *      provider really responds (the resolver only checks env vars).
+ *
+ * The deterministic baseline contract: works without LLM. With no
+ * provider reachable, the output is still useful — it carries the
+ * setup hints.
+ */
+export const aiStatusCommand = {
+    name: 'ai-status',
+    description: 'Report which AI provider shrk would use right now, with setup or upgrade hints. `--ping` verifies the provider actually responds. Read-only.',
+    usage: 'shrk ai-status [--provider auto|ollama|llamacpp|claude|gemini] [--ping] [--ping-timeout <ms>] [--json]',
+    async run(args) {
+        const providerKind = flagString(args, 'provider');
+        const json = flagBool(args, 'json');
+        const wantPing = flagBool(args, 'ping');
+        const pingTimeoutMs = flagNumber(args, 'ping-timeout') ?? 8000;
+        const selection = selectAiProvider(providerKind);
+        const ai = buildAiBlock({ selection, userOptedOut: false });
+        let ping = null;
+        if (wantPing) {
+            ping = selection.provider
+                ? await pingProvider(selection.provider, pingTimeoutMs)
+                : { ok: false, reason: 'no provider reachable — nothing to ping', elapsedMs: 0 };
+        }
+        if (json) {
+            process.stdout.write(asJson({
+                ai,
+                ...(ping ? { ping } : {}),
+            }) + '\n');
+            return ai.reachable && (!ping || ping.ok) ? 0 : 1;
+        }
+        process.stdout.write(header('AI status'));
+        process.stdout.write(kv('reachable', ai.reachable ? 'yes' : 'no') + '\n');
+        process.stdout.write(kv('requested provider', ai.requestedProvider) + '\n');
+        process.stdout.write(kv('resolved provider', ai.providerId ?? '(none)') + '\n');
+        if (ping) {
+            process.stdout.write(kv('ping', ping.ok
+                ? `ok in ${ping.elapsedMs}ms` + (ping.model ? ` (model: ${ping.model})` : '')
+                : `failed: ${ping.reason}`) + '\n');
+        }
+        process.stdout.write('\n');
+        process.stdout.write(renderAiBlockMarkdown(ai));
+        return ai.reachable && (!ping || ping.ok) ? 0 : 1;
+    },
+};
+async function pingProvider(provider, timeoutMs) {
+    const start = Date.now();
+    // Tiny prompt with bounded output — we just want to prove the round-trip works.
+    const requestPromise = provider.send({
+        messages: [
+            { role: AiMessageRole.System, content: 'Respond with the single word: ok' },
+            { role: AiMessageRole.User, content: 'ping' },
+        ],
+        maxTokens: 8,
+    });
+    const timeoutPromise = new Promise((resolve) => {
+        setTimeout(() => resolve({ ok: false, error: new Error(`timed out after ${timeoutMs}ms`) }), timeoutMs);
+    });
+    try {
+        const res = (await Promise.race([requestPromise, timeoutPromise]));
+        const elapsedMs = Date.now() - start;
+        if (!('value' in res) || !res.ok) {
+            const reason = 'error' in res
+                ? res.error.message ?? String(res.error)
+                : 'no response';
+            return { ok: false, reason, elapsedMs };
+        }
+        const value = res.value;
+        return {
+            ok: true,
+            elapsedMs,
+            ...(value.model ? { model: value.model } : {}),
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            reason: e.message,
+            elapsedMs: Date.now() - start,
+        };
+    }
+}

package/dist/commands/api-diff.command.d.ts

@@ -0,0 +1,11 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk api-diff` — compare the current code-graph's public-API
+ * surface to a saved baseline (or another snapshot file).
+ *
+ * Sub-verbs:
+ *   - shrk api-diff capture --output <path>     write the current surface to disk
+ *   - shrk api-diff <baseline.json>             diff current vs baseline
+ */
+export declare const apiDiffCommand: ICommandHandler;
+//# sourceMappingURL=api-diff.command.d.ts.map

package/dist/commands/api-diff.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-diff.command.d.ts","sourceRoot":"","sources":["../../src/commands/api-diff.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,eAoB5B,CAAC"}

package/dist/commands/api-diff.command.js

@@ -0,0 +1,144 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { diffApiSurfaces, extractApiSurface, extractApiSurfaceWithProgram, } from '@shrkcrft/api-surface-diff';
+import { GraphStore } from '@shrkcrft/graph';
+import { flagBool, flagList, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+/**
+ * `shrk api-diff` — compare the current code-graph's public-API
+ * surface to a saved baseline (or another snapshot file).
+ *
+ * Sub-verbs:
+ *   - shrk api-diff capture --output <path>     write the current surface to disk
+ *   - shrk api-diff <baseline.json>             diff current vs baseline
+ */
+export const apiDiffCommand = {
+    name: 'api-diff',
+    description: 'Compare the current public API surface to a saved baseline. Reports added / removed / kind-changed / moved symbols, with breaking-change severity.',
+    usage: 'shrk api-diff capture --output <path> [--packages @scope/a,@scope/b] [--with-signatures] | shrk api-diff <baseline.json> [--packages @scope/a,@scope/b] [--with-signatures] [--json] [--fail-on-breaking]   (--packages takes EXACT workspace package names, comma-separated or repeated)',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const wantJson = flagBool(args, 'json');
+        const sub = args.positional[0];
+        if (!sub) {
+            process.stderr.write(this.usage + '\n');
+            return 2;
+        }
+        if (sub === 'capture') {
+            return runCapture(args, cwd, wantJson);
+        }
+        return runDiff(args, cwd, wantJson, sub);
+    },
+};
+async function runCapture(args, cwd, wantJson) {
+    const outputFlag = flagString(args, 'output');
+    if (!outputFlag) {
+        process.stderr.write('shrk api-diff capture requires --output <path>\n');
+        return 2;
+    }
+    const surface = readSurfaceFromCwd(cwd, args);
+    if (!surface)
+        return 1;
+    const abs = nodePath.isAbsolute(outputFlag) ? outputFlag : nodePath.resolve(cwd, outputFlag);
+    mkdirSync(nodePath.dirname(abs), { recursive: true });
+    writeFileSync(abs, JSON.stringify(surface, null, 2), 'utf8');
+    if (wantJson) {
+        process.stdout.write(asJson({ ok: true, wrote: abs, total: surface.total }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header('API surface capture'));
+    process.stdout.write(kv('wrote', abs) + '\n');
+    process.stdout.write(kv('symbols', String(surface.total)) + '\n');
+    return 0;
+}
+async function runDiff(args, cwd, wantJson, baselinePath) {
+    const baselineAbs = nodePath.isAbsolute(baselinePath)
+        ? baselinePath
+        : nodePath.resolve(cwd, baselinePath);
+    let baseline;
+    try {
+        baseline = JSON.parse(readFileSync(baselineAbs, 'utf8'));
+    }
+    catch (e) {
+        process.stderr.write(`Baseline read error: ${e.message}\n`);
+        return 2;
+    }
+    const current = readSurfaceFromCwd(cwd, args);
+    if (!current)
+        return 1;
+    const diff = diffApiSurfaces(baseline, current);
+    const failOnBreaking = flagBool(args, 'fail-on-breaking');
+    if (wantJson) {
+        process.stdout.write(asJson(diff) + '\n');
+        return failOnBreaking && diff.breakingCount > 0 ? 1 : 0;
+    }
+    process.stdout.write(header('API surface diff'));
+    process.stdout.write(kv('schema', diff.schema) + '\n');
+    process.stdout.write(kv('baseline symbols', String(diff.baselineTotal)) + '\n');
+    process.stdout.write(kv('current symbols', String(diff.currentTotal)) + '\n');
+    process.stdout.write(kv('added', String(diff.added)) + '\n');
+    process.stdout.write(kv('removed', String(diff.removed)) + '\n');
+    process.stdout.write(kv('changed', String(diff.changed)) + '\n');
+    process.stdout.write(kv('breaking', String(diff.breakingCount)) + '\n');
+    if (diff.entries.length === 0) {
+        process.stdout.write('\nNo changes.\n');
+        return 0;
+    }
+    process.stdout.write('\nEntries:\n');
+    for (const e of diff.entries.slice(0, 80)) {
+        process.stdout.write(`  [${e.severity}] [${e.kind}] ${e.message}\n`);
+    }
+    if (diff.entries.length > 80) {
+        process.stdout.write(`  … (${diff.entries.length - 80} more)\n`);
+    }
+    return failOnBreaking && diff.breakingCount > 0 ? 1 : 0;
+}
+function readSurfaceFromCwd(cwd, args) {
+    const packages = flagList(args, 'packages');
+    const withSignatures = flagBool(args, 'with-signatures');
+    let surface;
+    if (withSignatures) {
+        const result = extractApiSurfaceWithProgram({
+            projectRoot: cwd,
+            ...(packages.length > 0 ? { packageFilter: packages } : {}),
+        });
+        for (const d of result.diagnostics.slice(0, 5)) {
+            process.stderr.write(`! ${d}\n`);
+        }
+        surface = result.surface;
+    }
+    else {
+        const store = new GraphStore(cwd);
+        if (!store.exists()) {
+            process.stderr.write("Code-graph store missing. Run 'shrk graph index' first.\n");
+            return undefined;
+        }
+        const snap = store.loadSnapshot();
+        surface = extractApiSurface(snap, {
+            ...(packages.length > 0 ? { packageFilter: packages } : {}),
+        });
+    }
+    return applyPackageFilterGuard(surface, packages);
+}
+/**
+ * A `--packages` filter that resolves to no known workspace package is a quiet
+ * footgun: the extractor silently returns a 0-symbol surface (exit 0) that is
+ * indistinguishable from a package that genuinely exports nothing. When EVERY
+ * requested filter is unknown, abort loudly; when only some are, warn and keep
+ * the partial result.
+ */
+function applyPackageFilterGuard(surface, packages) {
+    const unmatched = surface.unmatchedFilters ?? [];
+    if (packages.length === 0 || unmatched.length === 0)
+        return surface;
+    const matched = Object.keys(surface.countsByPackage).filter((k) => k !== '<no-package>');
+    if (unmatched.length === packages.length) {
+        process.stderr.write(`--packages matched no known workspace package: ${unmatched.join(', ')}\n` +
+            '  Pass exact package names (npm "name", e.g. @shrkcrft/core), comma-separated or repeated.\n');
+        return undefined;
+    }
+    process.stderr.write(`! --packages: ignoring unknown package(s): ${unmatched.join(', ')}` +
+        (matched.length > 0 ? ` (matched: ${matched.join(', ')})` : '') +
+        '\n');
+    return surface;
+}

package/dist/commands/apply.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply.command.d.ts","sourceRoot":"","sources":["../../src/commands/apply.command.ts"],"names":[],"mappings":"AAqDA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAyLhC,eAAO,MAAM,YAAY,EAAE,eAyrB1B,CAAC"}
+{"version":3,"file":"apply.command.d.ts","sourceRoot":"","sources":["../../src/commands/apply.command.ts"],"names":[],"mappings":"AAqDA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAyLhC,eAAO,MAAM,YAAY,EAAE,eAisB1B,CAAC"}