@shrkcrft/cli 0.1.0-alpha.2

package/dist/commands/profiles.command.js

@@ -0,0 +1,151 @@
+/**
+ * `shrk profiles ...` — unified read-only surface for all pack-/local-
+ * contributed profiles (plugin lifecycle, migration, and future kinds).
+ */
+import { findProfile, inspectSharkcraft, listProfileIssues, listProfiles, ProfileKind, } from '@shrkcrft/inspector';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, header } from "../output/format-output.js";
+function parseKind(value) {
+    if (!value)
+        return undefined;
+    const known = Object.values(ProfileKind);
+    if (known.includes(value))
+        return value;
+    return undefined;
+}
+export const profilesListCommand = {
+    name: 'list',
+    description: 'List all registered profiles (plugin-lifecycle, migration, ...).',
+    usage: 'shrk profiles list [--kind <kind>] [--json]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const kind = parseKind(flagString(args, 'kind'));
+        const entries = await listProfiles(inspection, kind ? { kind } : {});
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(entries) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Profiles (${entries.length}${kind ? `, kind=${kind}` : ''})`));
+        if (entries.length === 0) {
+            process.stdout.write('  (none — contribute via packs: pluginLifecycleProfileFiles, migrationProfileFiles, etc.)\n');
+            return 0;
+        }
+        for (const e of entries) {
+            const src = e.source === 'pack' ? `pack:${e.packageName ?? '?'}` : e.source;
+            process.stdout.write(`  • ${e.kind.padEnd(18)} ${e.id.padEnd(24)} ${e.title}  [${src}]\n`);
+        }
+        return 0;
+    },
+};
+export const profilesGetCommand = {
+    name: 'get',
+    description: 'Show one profile by id (and optional --kind).',
+    usage: 'shrk profiles get <id> [--kind <kind>] [--json]',
+    async run(args) {
+        const id = args.positional[0];
+        if (!id) {
+            process.stderr.write('Usage: shrk profiles get <id>\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const kind = parseKind(flagString(args, 'kind'));
+        const entry = await findProfile(inspection, id, kind);
+        if (!entry) {
+            process.stderr.write(`Unknown profile "${id}"${kind ? ` (kind=${kind})` : ''}.\n`);
+            return 2;
+        }
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(entry) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Profile ${entry.id} (${entry.kind})`));
+        process.stdout.write(`  title         ${entry.title}\n`);
+        if (entry.description)
+            process.stdout.write(`  description   ${entry.description}\n`);
+        process.stdout.write(`  source        ${entry.source}${entry.packageName ? ' (' + entry.packageName + ')' : ''}\n`);
+        if (entry.sourceFile)
+            process.stdout.write(`  sourceFile    ${entry.sourceFile}\n`);
+        if (entry.tags && entry.tags.length > 0)
+            process.stdout.write(`  tags          ${entry.tags.join(', ')}\n`);
+        if (entry.appliesWhen && entry.appliesWhen.length > 0) {
+            process.stdout.write(`  appliesWhen   ${entry.appliesWhen.join(', ')}\n`);
+        }
+        return 0;
+    },
+};
+export const profilesDoctorCommand = {
+    name: 'doctor',
+    description: 'Surface load issues across all profile kinds.',
+    usage: 'shrk profiles doctor [--json]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const issues = await listProfileIssues(inspection);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({ issues }) + '\n');
+            return issues.some((i) => i.severity === 'error') ? 1 : 0;
+        }
+        process.stdout.write(header('Profile registry doctor'));
+        if (issues.length === 0) {
+            process.stdout.write('  ok — no load issues across registered profile kinds.\n');
+            return 0;
+        }
+        for (const i of issues) {
+            process.stdout.write(`  ${i.severity.padEnd(7)} [${i.code}] ${i.message}\n`);
+        }
+        return issues.some((i) => i.severity === 'error') ? 1 : 0;
+    },
+};
+export const profilesSearchCommand = {
+    name: 'search',
+    description: 'Search registered profiles by free-text token across id / title / tags.',
+    usage: 'shrk profiles search <query> [--kind <kind>] [--json]',
+    async run(args) {
+        const query = args.positional[0];
+        if (!query) {
+            process.stderr.write('Usage: shrk profiles search <query>\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const kind = parseKind(flagString(args, 'kind'));
+        const all = await listProfiles(inspection, kind ? { kind } : {});
+        const q = query.toLowerCase();
+        const matches = all.filter((e) => {
+            const haystack = `${e.id} ${e.title} ${(e.tags ?? []).join(' ')} ${e.description ?? ''}`.toLowerCase();
+            return haystack.includes(q);
+        });
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(matches) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Profiles matching "${query}" (${matches.length})`));
+        for (const e of matches) {
+            process.stdout.write(`  • ${e.kind.padEnd(18)} ${e.id.padEnd(24)} ${e.title}\n`);
+        }
+        if (matches.length === 0)
+            process.stdout.write('  (no matches)\n');
+        return 0;
+    },
+};
+export const profilesCommand = {
+    name: 'profiles',
+    description: 'List / inspect pack-contributed profiles (plugin-lifecycle, migration, conventions, …).',
+    usage: 'shrk profiles list|get|doctor|search ...',
+    async run(args) {
+        const sub = args.positional[0];
+        args.positional = args.positional.slice(1);
+        if (sub === 'list')
+            return profilesListCommand.run(args);
+        if (sub === 'get')
+            return profilesGetCommand.run(args);
+        if (sub === 'doctor')
+            return profilesDoctorCommand.run(args);
+        if (sub === 'search')
+            return profilesSearchCommand.run(args);
+        process.stderr.write('Usage: shrk profiles list|get|doctor|search ...\n');
+        return 2;
+    },
+};

package/dist/commands/provenance.command.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Asset provenance CLI surface.
+ *
+ *   - `shrk provenance list [--kind <k>] [--id <id>] [--limit N]`
+ *   - `shrk provenance show <assetId> [--kind <k>]`
+ *   - `shrk provenance report`
+ *
+ * Read-only — the ledger is written by the authoring commands. CLI never
+ * accepts arbitrary write requests.
+ */
+import { type ICommandHandler } from '../command-registry.js';
+export declare const provenanceListCommand: ICommandHandler;
+export declare const provenanceShowCommand: ICommandHandler;
+export declare const provenanceReportCommand: ICommandHandler;
+/**
+ * `shrk provenance missing`. Lists local-asset entries that have no
+ * provenance ledger record. Old entries are exempted (advisory only).
+ */
+export declare const provenanceMissingCommand: ICommandHandler;
+/**
+ * `shrk provenance doctor`. Schema-validates every ledger entry:
+ * required fields present, generatedAt parses, operation/source match
+ * the enums.
+ */
+export declare const provenanceDoctorCommand: ICommandHandler;
+//# sourceMappingURL=provenance.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.command.d.ts","sourceRoot":"","sources":["../../src/commands/provenance.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAYH,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,qBAAqB,EAAE,eA+BnC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAmCnC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAerC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,eAwEtC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,eA2ErC,CAAC"}

package/dist/commands/provenance.command.js

@@ -0,0 +1,237 @@
+/**
+ * Asset provenance CLI surface.
+ *
+ *   - `shrk provenance list [--kind <k>] [--id <id>] [--limit N]`
+ *   - `shrk provenance show <assetId> [--kind <k>]`
+ *   - `shrk provenance report`
+ *
+ * Read-only — the ledger is written by the authoring commands. CLI never
+ * accepts arbitrary write requests.
+ */
+import { buildProvenanceReport, inspectSharkcraft, listProvenance, readProvenance, renderProvenanceMarkdown, showProvenance, } from '@shrkcrft/inspector';
+import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, header } from "../output/format-output.js";
+export const provenanceListCommand = {
+    name: 'list',
+    description: 'List provenance ledger entries (most-recent first).',
+    usage: 'shrk provenance list [--kind <assetKind>] [--id <assetId>] [--operation <op>] [--limit N] [--json]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const entries = listProvenance(cwd, {
+            ...(flagString(args, 'kind') ? { assetKind: flagString(args, 'kind') } : {}),
+            ...(flagString(args, 'id') ? { assetId: flagString(args, 'id') ?? undefined } : {}),
+            ...(flagString(args, 'operation')
+                ? { operation: flagString(args, 'operation') }
+                : {}),
+            ...(flagNumber(args, 'limit') ? { limit: flagNumber(args, 'limit') ?? undefined } : {}),
+        });
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(entries) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Provenance entries (${entries.length})`));
+        if (entries.length === 0) {
+            process.stdout.write('  (ledger is empty — run a `shrk knowledge author --write-preview` to start it)\n');
+            return 0;
+        }
+        for (const e of entries) {
+            process.stdout.write(`  ${e.generatedAt}  ${e.operation.padEnd(10)} ${e.assetKind}:${e.assetId}  ← ${e.source}${e.reason ? ` — ${e.reason}` : ''}\n`);
+        }
+        return 0;
+    },
+};
+export const provenanceShowCommand = {
+    name: 'show',
+    description: 'Show all provenance entries for one asset id.',
+    usage: 'shrk provenance show <assetId> [--kind <assetKind>] [--json]',
+    async run(args) {
+        const id = args.positional[0] ?? flagString(args, 'id');
+        if (!id) {
+            process.stderr.write('Usage: shrk provenance show <assetId>\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const result = showProvenance(cwd, id, flagString(args, 'kind'));
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(result) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Provenance: ${result.assetKind}:${result.assetId}`));
+        if (result.entries.length === 0) {
+            process.stdout.write('  (no provenance entries — this asset has no recorded authoring history)\n');
+            return 0;
+        }
+        for (const e of result.entries) {
+            process.stdout.write(`  ${e.generatedAt}  ${e.operation}  ← ${e.source}${e.author ? ` (${e.author})` : ''}\n`);
+            if (e.reason)
+                process.stdout.write(`    reason: ${e.reason}\n`);
+            if (e.previewPath)
+                process.stdout.write(`    preview: ${e.previewPath}\n`);
+            if (e.relatedTask)
+                process.stdout.write(`    task: ${e.relatedTask}\n`);
+        }
+        return 0;
+    },
+};
+export const provenanceReportCommand = {
+    name: 'report',
+    description: 'Summary report of the asset provenance ledger.',
+    usage: 'shrk provenance report [--recent N] [--json]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const recent = flagNumber(args, 'recent') ?? 10;
+        const report = buildProvenanceReport(cwd, recent);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(report) + '\n');
+            return 0;
+        }
+        process.stdout.write(renderProvenanceMarkdown(report));
+        return 0;
+    },
+};
+/**
+ * `shrk provenance missing`. Lists local-asset entries that have no
+ * provenance ledger record. Old entries are exempted (advisory only).
+ */
+export const provenanceMissingCommand = {
+    name: 'missing',
+    description: 'List local assets (rules / knowledge / templates) without provenance entries. Advisory.',
+    usage: 'shrk provenance missing [--kind <kind>] [--json]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const ledger = readProvenance(cwd);
+        const seen = new Set();
+        for (const entry of ledger) {
+            seen.add(`${entry.assetKind}:${entry.assetId}`);
+        }
+        const kindFilter = flagString(args, 'kind');
+        const missing = [];
+        for (const k of inspection.knowledgeEntries) {
+            const sourceInfo = inspection.entrySources.get(k.id);
+            if (sourceInfo?.type !== 'local')
+                continue; // only flag local — pack assets have their own provenance flow
+            const kind = k.type === 'rule' ? 'rule' : 'knowledge';
+            if (kindFilter && kindFilter !== kind)
+                continue;
+            const ledgerKey = `${kind}:${k.id}`;
+            if (seen.has(ledgerKey))
+                continue;
+            // Asset-kind name in ledger may also be the literal entry.type — try both.
+            if (seen.has(`${k.type}:${k.id}`))
+                continue;
+            missing.push({ kind, id: k.id, title: k.title, source: 'local' });
+        }
+        for (const t of inspection.templates) {
+            const sourceInfo = inspection.templateSources.get(t.id);
+            if (sourceInfo?.type !== 'local')
+                continue;
+            if (kindFilter && kindFilter !== 'template')
+                continue;
+            if (seen.has(`template:${t.id}`))
+                continue;
+            missing.push({
+                kind: 'template',
+                id: t.id,
+                title: t.title,
+                source: 'local',
+            });
+        }
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({
+                schema: 'sharkcraft.provenance-missing/v1',
+                generatedAt: new Date().toISOString(),
+                missing,
+                total: missing.length,
+            }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Assets without provenance (${missing.length})`));
+        if (missing.length === 0) {
+            process.stdout.write('  All local assets have at least one provenance entry. ✓\n');
+            return 0;
+        }
+        for (const m of missing.slice(0, 100)) {
+            process.stdout.write(`  ${m.kind.padEnd(10)} ${m.id}${m.title ? ` — ${m.title}` : ''}\n`);
+        }
+        process.stdout.write('\nNote: missing provenance is advisory. Use the authoring CLI ' +
+            '(`shrk knowledge update <id> --reason "..."`, `shrk rules scaffold ...`) ' +
+            'to record a record going forward.\n');
+        return 0;
+    },
+};
+/**
+ * `shrk provenance doctor`. Schema-validates every ledger entry:
+ * required fields present, generatedAt parses, operation/source match
+ * the enums.
+ */
+export const provenanceDoctorCommand = {
+    name: 'doctor',
+    description: 'Validate the provenance ledger — schema + required fields.',
+    usage: 'shrk provenance doctor [--json]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const ledger = readProvenance(cwd);
+        const validOperations = new Set([
+            'add',
+            'update',
+            'remove',
+            'preview',
+            'apply',
+            'acknowledge',
+        ]);
+        const validSources = new Set(['manual', 'agent', 'cli', 'session', 'unknown']);
+        const issues = [];
+        for (let i = 0; i < ledger.length; i += 1) {
+            const e = ledger[i];
+            if (!e.assetId)
+                issues.push({ index: i, issue: 'missing assetId' });
+            if (!e.assetKind)
+                issues.push({ index: i, assetId: e.assetId, issue: 'missing assetKind' });
+            if (!e.generatedAt || Number.isNaN(Date.parse(e.generatedAt))) {
+                issues.push({
+                    index: i,
+                    assetId: e.assetId,
+                    issue: `invalid generatedAt: ${e.generatedAt}`,
+                });
+            }
+            if (!validOperations.has(e.operation)) {
+                issues.push({
+                    index: i,
+                    assetId: e.assetId,
+                    issue: `unknown operation: ${e.operation}`,
+                });
+            }
+            if (!validSources.has(e.source)) {
+                issues.push({
+                    index: i,
+                    assetId: e.assetId,
+                    issue: `unknown source: ${e.source}`,
+                });
+            }
+        }
+        const ok = issues.length === 0;
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({
+                schema: 'sharkcraft.provenance-doctor/v1',
+                generatedAt: new Date().toISOString(),
+                total: ledger.length,
+                issues,
+                ok,
+            }) + '\n');
+            return ok ? 0 : 1;
+        }
+        process.stdout.write(header(`Provenance ledger doctor`));
+        process.stdout.write(`  total entries:  ${ledger.length}\n`);
+        process.stdout.write(`  issues:         ${issues.length}\n`);
+        if (issues.length === 0) {
+            process.stdout.write('\n  Ledger is valid. ✓\n');
+            return 0;
+        }
+        process.stdout.write('\nIssues:\n');
+        for (const issue of issues.slice(0, 50)) {
+            process.stdout.write(`  ! [${issue.index}] ${issue.assetId ?? '(no id)'} — ${issue.issue}\n`);
+        }
+        return 1;
+    },
+};

package/dist/commands/quality.command.d.ts

@@ -0,0 +1,5 @@
+import { type IQualityReport } from '@shrkcrft/inspector';
+import { type ICommandHandler } from '../command-registry.js';
+export declare const qualityCommand: ICommandHandler;
+export type { IQualityReport };
+//# sourceMappingURL=quality.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"quality.command.d.ts","sourceRoot":"","sources":["../../src/commands/quality.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAOhC,eAAO,MAAM,cAAc,EAAE,eAqE5B,CAAC;AAEF,YAAY,EAAE,cAAc,EAAE,CAAC"}

package/dist/commands/quality.command.js

@@ -0,0 +1,69 @@
+import { buildQualityReport, inspectSharkcraft, } from '@shrkcrft/inspector';
+import { flagBool, flagNumber, resolveCwd, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+// `quality baseline {create|compare|update|show|diff|prune|history}`
+// removed. The baseline machinery was hidden / unused; `doctor` and
+// `drift` cover the actionable cases.
+export const qualityCommand = {
+    name: 'quality',
+    description: 'High-level quality gate: orchestrates doctor / boundaries / coverage / drift / context tests / agent tests / packs doctor. Designed to be the single command to run locally before opening a PR or in CI.',
+    usage: 'shrk [--cwd <dir>] quality [--strict] [--ci] [--min-readiness <n>] [--require-boundary-clean] [--require-drift-clean] [--require-agent-tests] [--require-context-tests] [--require-pack-signatures] [--json]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const strict = flagBool(args, 'strict');
+        const ci = flagBool(args, 'ci');
+        const wantJson = flagBool(args, 'json') || ci;
+        const inspection = await inspectSharkcraft({
+            cwd,
+            ...(flagBool(args, 'require-pack-signatures') ? { verifyPackSignatures: true } : {}),
+        });
+        const cfgGates = inspection.config?.qualityGates ?? {};
+        const config = {
+            ...cfgGates,
+            ...(flagNumber(args, 'min-readiness') !== undefined
+                ? { minReadiness: flagNumber(args, 'min-readiness') }
+                : {}),
+            ...(flagBool(args, 'require-boundary-clean') ? { requireBoundaryClean: true } : {}),
+            ...(flagBool(args, 'require-drift-clean') ? { requireDriftClean: true } : {}),
+            ...(flagBool(args, 'require-agent-tests') ? { requireAgentTests: true } : {}),
+            ...(flagBool(args, 'require-context-tests') ? { requireContextTests: true } : {}),
+            ...(flagBool(args, 'require-pack-signatures') ? { requirePackSignatures: true } : {}),
+        };
+        const report = await buildQualityReport({ inspection, config, strict });
+        if (wantJson) {
+            process.stdout.write(asJson(report) + '\n');
+            return report.overall === 'fail' ? 1 : 0;
+        }
+        process.stdout.write(header('SharkCraft quality gate'));
+        process.stdout.write(kv('overall', report.overall) + '\n');
+        process.stdout.write(kv('score', `${report.score}%`) + '\n');
+        process.stdout.write(kv('blockers', String(report.blockers)) + '\n');
+        process.stdout.write(kv('warnings', String(report.warnings)) + '\n\n');
+        for (const g of report.gates) {
+            const tag = !g.executed
+                ? 'SKIP '
+                : g.passed
+                    ? 'OK   '
+                    : g.blocking
+                        ? 'BLOCK'
+                        : 'WARN ';
+            process.stdout.write(`  ${tag}  ${g.label}\n`);
+            for (const n of g.notes)
+                process.stdout.write(`         ↳ ${n}\n`);
+        }
+        if (report.drift && (report.drift.counts.error > 0 || report.drift.counts.warning > 0)) {
+            process.stdout.write('\nDrift summary:\n');
+            process.stdout.write(`  errors=${report.drift.counts.error}  warnings=${report.drift.counts.warning}  info=${report.drift.counts.info}\n`);
+            for (const f of report.drift.findings.slice(0, 5)) {
+                process.stdout.write(`  • ${f.severity}: ${f.category} — ${f.message}\n`);
+            }
+        }
+        if (report.nextRecommendations.length > 0) {
+            process.stdout.write('\nRecommendations:\n');
+            for (const r of report.nextRecommendations)
+                process.stdout.write(`  • ${r}\n`);
+        }
+        process.stdout.write(`\nVerdict: ${report.overall.toUpperCase()}\n`);
+        return report.overall === 'fail' ? 1 : 0;
+    },
+};

package/dist/commands/recommend.command.d.ts

@@ -0,0 +1,4 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const recommendCommand: ICommandHandler;
+export declare function looksLikePlanning(query: string): boolean;
+//# sourceMappingURL=recommend.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recommend.command.d.ts","sourceRoot":"","sources":["../../src/commands/recommend.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAShC,eAAO,MAAM,gBAAgB,EAAE,eA0K9B,CAAC;AAoGF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAcxD"}