@shrkcrft/cli 0.1.0-alpha.2

package/dist/commands/start-here.command.d.ts

@@ -0,0 +1,3 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const startHereCommand: ICommandHandler;
+//# sourceMappingURL=start-here.command.d.ts.map

package/dist/commands/start-here.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-here.command.d.ts","sourceRoot":"","sources":["../../src/commands/start-here.command.ts"],"names":[],"mappings":"AAKA,OAAO,EAAwB,KAAK,eAAe,EAAmB,MAAM,wBAAwB,CAAC;AAarG,eAAO,MAAM,gBAAgB,EAAE,eAwB9B,CAAC"}

package/dist/commands/start-here.command.js

@@ -0,0 +1,35 @@
+import { buildStartHereReport, renderStartHereText, } from '@shrkcrft/inspector';
+import { flagBool, flagString } from "../command-registry.js";
+import { asJson } from "../output/format-output.js";
+const VALID_FLOWS = [
+    'onboard',
+    'brief',
+    'dev',
+    'review',
+    'governance',
+    'packs',
+    'release',
+];
+export const startHereCommand = {
+    name: 'start-here',
+    description: 'Human entry point — 30-second explanation + 5 primary flows + safety pledge.',
+    usage: 'shrk start-here [--flow onboard|brief|dev|review|governance|packs|release] [--json]',
+    async run(args) {
+        const flowRaw = flagString(args, 'flow');
+        let flow = null;
+        if (flowRaw) {
+            if (!VALID_FLOWS.includes(flowRaw)) {
+                process.stderr.write(`Unknown --flow "${flowRaw}". Use ${VALID_FLOWS.join('|')}.\n`);
+                return 2;
+            }
+            flow = flowRaw;
+        }
+        const report = buildStartHereReport(flow);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(report) + '\n');
+            return 0;
+        }
+        process.stdout.write(renderStartHereText(report));
+        return 0;
+    },
+};

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

@@ -0,0 +1,3 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const statsCommand: ICommandHandler;
+//# sourceMappingURL=stats.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stats.command.d.ts","sourceRoot":"","sources":["../../src/commands/stats.command.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAoBhC,eAAO,MAAM,YAAY,EAAE,eAqF1B,CAAC"}

package/dist/commands/stats.command.js

@@ -0,0 +1,88 @@
+import { buildRepositoryStats } from '@shrkcrft/inspector';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+const BYTES_PER_KB = 1024;
+const BYTES_PER_MB = BYTES_PER_KB * 1024;
+function humanBytes(bytes) {
+    if (bytes >= BYTES_PER_MB)
+        return (bytes / BYTES_PER_MB).toFixed(2) + ' MB';
+    if (bytes >= BYTES_PER_KB)
+        return (bytes / BYTES_PER_KB).toFixed(1) + ' KB';
+    return bytes + ' B';
+}
+function rightPad(s, n) {
+    return s.length >= n ? s : s + ' '.repeat(n - s.length);
+}
+function leftPad(s, n) {
+    return s.length >= n ? s : ' '.repeat(n - s.length) + s;
+}
+export const statsCommand = {
+    name: 'stats',
+    description: 'Repository statistics — per-language file counts, lines of code (code/comment/blank), bytes, averages, largest files.',
+    usage: 'shrk [--cwd <dir>] stats [--json] [--top <n>] [--language <id>]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const topStr = flagString(args, 'top');
+        const top = topStr !== undefined ? Math.max(0, Number(topStr) || 0) : undefined;
+        const language = flagString(args, 'language');
+        const stats = await buildRepositoryStats({
+            cwd,
+            ...(top !== undefined ? { maxTopFiles: top } : {}),
+            ...(language ? { language } : {}),
+        });
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(stats) + '\n');
+            return 0;
+        }
+        process.stdout.write(header('Repository statistics'));
+        process.stdout.write(kv('project root', stats.projectRoot) + '\n');
+        process.stdout.write(kv('generated at', stats.generatedAt) + '\n');
+        if (stats.truncated) {
+            process.stdout.write(kv('truncated', 'yes — file cap reached, results partial') + '\n');
+        }
+        process.stdout.write('\n');
+        const t = stats.totals;
+        process.stdout.write(`Totals\n`);
+        process.stdout.write(`  files:        ${t.files.toLocaleString()}\n`);
+        process.stdout.write(`  bytes:        ${t.bytes.toLocaleString()} (${humanBytes(t.bytes)})\n`);
+        process.stdout.write(`  total lines:  ${t.totalLines.toLocaleString()}\n`);
+        process.stdout.write(`  code lines:   ${t.codeLines.toLocaleString()}\n`);
+        process.stdout.write(`  comment:      ${t.commentLines.toLocaleString()}\n`);
+        process.stdout.write(`  blank:        ${t.blankLines.toLocaleString()}\n`);
+        process.stdout.write('\n');
+        if (stats.byLanguage.length === 0) {
+            process.stdout.write('No recognized source files found.\n');
+            return 0;
+        }
+        process.stdout.write(`Per language\n`);
+        const langW = 14;
+        const numW = 9;
+        process.stdout.write('  ' +
+            rightPad('language', langW) +
+            leftPad('files', numW) +
+            leftPad('code', numW + 1) +
+            leftPad('comment', numW + 1) +
+            leftPad('blank', numW + 1) +
+            leftPad('bytes', numW + 3) +
+            leftPad('avg/file', numW + 2) +
+            '\n');
+        for (const l of stats.byLanguage) {
+            process.stdout.write('  ' +
+                rightPad(l.language, langW) +
+                leftPad(l.files.toLocaleString(), numW) +
+                leftPad(l.codeLines.toLocaleString(), numW + 1) +
+                leftPad(l.commentLines.toLocaleString(), numW + 1) +
+                leftPad(l.blankLines.toLocaleString(), numW + 1) +
+                leftPad(humanBytes(l.bytes), numW + 3) +
+                leftPad(l.averageFileLines.toLocaleString() + ' L', numW + 2) +
+                '\n');
+        }
+        if (stats.topFiles.length > 0) {
+            process.stdout.write('\nLargest files\n');
+            for (const f of stats.topFiles) {
+                process.stdout.write(`  ${rightPad(humanBytes(f.bytes), 10)} ${leftPad(f.lines.toLocaleString() + ' L', 10)}  ${f.language.padEnd(12)} ${f.path}\n`);
+            }
+        }
+        return 0;
+    },
+};

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

@@ -0,0 +1,15 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk surface`. Top-level introspection + opt-in management
+ * for the adaptive command surface. Subcommands:
+ *
+ *   - list                  every command grouped by tier
+ *   - enable  <command>     promote experimental → callable
+ *   - disable <command>     undo a prior enable
+ *   - hide    <command>     hide an extended command from --help
+ *   - unhide  <command>     reverse hide
+ *   - reset                 clear surface.enabled + surface.hidden
+ *   - explain <command>     why this command has its current tier
+ */
+export declare const surfaceCommand: ICommandHandler;
+//# sourceMappingURL=surface.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"surface.command.d.ts","sourceRoot":"","sources":["../../src/commands/surface.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAiBhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,EAAE,eAmC5B,CAAC"}

package/dist/commands/surface.command.js

@@ -0,0 +1,328 @@
+import { flagBool, resolveCwd, } from "../command-registry.js";
+import { asJson, header, kv, table } from "../output/format-output.js";
+import { loadSurfaceContext } from "../surface/load-surface-context.js";
+import { buildSurfaceSummary, findCommandInSummary, } from "../surface/surface-summary.js";
+import { CommandTier } from "./command-catalog.js";
+import { applySurfaceEdit, defaultConfigFile, planSurfaceEdit, } from "../surface/surface-config-writer.js";
+/**
+ * `shrk surface`. Top-level introspection + opt-in management
+ * for the adaptive command surface. Subcommands:
+ *
+ *   - list                  every command grouped by tier
+ *   - enable  <command>     promote experimental → callable
+ *   - disable <command>     undo a prior enable
+ *   - hide    <command>     hide an extended command from --help
+ *   - unhide  <command>     reverse hide
+ *   - reset                 clear surface.enabled + surface.hidden
+ *   - explain <command>     why this command has its current tier
+ */
+export const surfaceCommand = {
+    name: 'surface',
+    description: 'Inspect or change the adaptive command surface (core / extended / experimental tiers).',
+    usage: 'shrk surface <list|enable|disable|hide|unhide|reset|explain> [name] [--write] [--json]',
+    async run(args) {
+        const [verb, ...rest] = args.positional;
+        const json = flagBool(args, 'json');
+        const write = flagBool(args, 'write');
+        const cwd = resolveCwd(args);
+        switch (verb) {
+            case undefined:
+            case 'list':
+                return await runList({ cwd, json });
+            case 'explain':
+                return await runExplain({ cwd, json, target: rest[0] });
+            case 'enable':
+                return await runMutate({ cwd, json, write, target: rest[0], op: 'enable' });
+            case 'disable':
+                return await runMutate({ cwd, json, write, target: rest[0], op: 'disable' });
+            case 'hide':
+                return await runMutate({ cwd, json, write, target: rest[0], op: 'hide' });
+            case 'unhide':
+                return await runMutate({ cwd, json, write, target: rest[0], op: 'unhide' });
+            case 'reset':
+                return await runReset({ cwd, json, write });
+            case 'profiles':
+                return await runProfiles({ cwd, json, sub: rest[0], target: rest[1] });
+            default:
+                process.stderr.write(`Unknown subcommand: surface ${verb}\nSee \`shrk surface --help\`.\n`);
+                return 2;
+        }
+    },
+};
+async function runProfiles(opts) {
+    const { context, inspection, availableProfiles, activeProfile } = await loadSurfaceContext({ cwd: opts.cwd });
+    void inspection;
+    void context;
+    if (!opts.sub || opts.sub === 'list') {
+        if (opts.json) {
+            process.stdout.write(asJson({
+                schema: 'sharkcraft.surface.profiles.v1',
+                active: activeProfile?.id ?? null,
+                profiles: availableProfiles,
+            }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header('Surface profiles'));
+        process.stdout.write(kv('active', activeProfile?.id ?? '(none — set via sharkcraft.config.ts surface.profile)') + '\n');
+        process.stdout.write('\n');
+        for (const p of availableProfiles) {
+            const isActive = activeProfile?.id === p.id;
+            const tag = isActive ? '*' : ' ';
+            const src = p.source === 'pack' ? ` (pack: ${p.pack})` : ` (builtin)`;
+            const hiddenCount = p.hidden?.length ?? 0;
+            const enabledCount = p.enabled?.length ?? 0;
+            process.stdout.write(`  ${tag} ${p.id.padEnd(14)} ${src.padEnd(20)} hides=${hiddenCount}, enables=${enabledCount}\n`);
+            process.stdout.write(`      ${p.description}\n`);
+        }
+        return 0;
+    }
+    if (opts.sub === 'get') {
+        if (!opts.target) {
+            process.stderr.write('Usage: shrk surface profiles get <id>\n');
+            return 2;
+        }
+        const found = availableProfiles.find((p) => p.id === opts.target);
+        if (!found) {
+            process.stderr.write(`Unknown profile: ${opts.target}\n`);
+            return 1;
+        }
+        if (opts.json) {
+            process.stdout.write(asJson(found) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Profile — ${found.id}`));
+        process.stdout.write(kv('description', found.description) + '\n');
+        process.stdout.write(kv('source', found.source + (found.pack ? ` (${found.pack})` : '')) + '\n');
+        process.stdout.write(kv('hidden', String(found.hidden?.length ?? 0)) + '\n');
+        process.stdout.write(kv('enabled', String(found.enabled?.length ?? 0)) + '\n');
+        if (found.hidden && found.hidden.length > 0) {
+            process.stdout.write('\nHidden:\n');
+            for (const h of found.hidden)
+                process.stdout.write(`  - ${h}\n`);
+        }
+        if (found.enabled && found.enabled.length > 0) {
+            process.stdout.write('\nEnabled:\n');
+            for (const e of found.enabled)
+                process.stdout.write(`  + ${e}\n`);
+        }
+        return 0;
+    }
+    process.stderr.write(`Unknown subcommand: surface profiles ${opts.sub}\nUse: list, get <id>\n`);
+    return 2;
+}
+async function runList({ cwd, json }) {
+    const { context, activeProfile } = await loadSurfaceContext({ cwd });
+    const summary = buildSurfaceSummary(context);
+    if (json) {
+        process.stdout.write(asJson({ ...summary, activeProfile: activeProfile?.id ?? null }) + '\n');
+        return 0;
+    }
+    renderSurfaceText(summary, activeProfile?.id);
+    return 0;
+}
+function renderSurfaceText(summary, activeProfileId) {
+    process.stdout.write(header('Command surface'));
+    process.stdout.write(kv('schema', summary.schema) + '\n');
+    process.stdout.write(kv('hash', summary.hash) + '\n');
+    process.stdout.write(kv('profile', activeProfileId ?? '(none — sharkcraft.config.ts surface.profile not set)') + '\n');
+    process.stdout.write(kv('core', String(summary.totals.core)) + '\n');
+    process.stdout.write(kv('extended', String(summary.totals.extended)) + '\n');
+    process.stdout.write(kv('experimental', String(summary.totals.experimental)) + '\n');
+    process.stdout.write(kv('visible in --help', String(summary.totals.visible)) + '\n');
+    process.stdout.write(kv('callable', String(summary.totals.callable)) + '\n');
+    process.stdout.write('\n');
+    printBucket('core', summary.tiers.core);
+    printBucket('extended', summary.tiers.extended);
+    printBucket('experimental', summary.tiers.experimental);
+    if (summary.warnings.length > 0) {
+        process.stdout.write('\nWarnings:\n');
+        for (const w of summary.warnings) {
+            process.stdout.write(`  ! ${w.code}: ${w.message}\n`);
+        }
+    }
+}
+function printBucket(label, items) {
+    process.stdout.write(`-- ${label} (${items.length}) --\n`);
+    if (items.length === 0) {
+        process.stdout.write('  (empty)\n');
+        return;
+    }
+    const rows = items.map((c) => {
+        const flags = [];
+        if (c.hidden)
+            flags.push('hidden');
+        if (c.enabled)
+            flags.push('enabled');
+        if (!c.callable)
+            flags.push('gated');
+        if (c.pack)
+            flags.push(`pack:${c.pack}`);
+        return [
+            '  ' + c.command,
+            c.source,
+            flags.join(','),
+            c.detail ?? '',
+        ];
+    });
+    process.stdout.write(table(rows) + '\n');
+}
+async function runExplain({ cwd, json, target }) {
+    if (!target) {
+        process.stderr.write('Usage: shrk surface explain <command>\n');
+        return 2;
+    }
+    const { context, activeProfile } = await loadSurfaceContext({ cwd });
+    const summary = buildSurfaceSummary(context);
+    const view = findCommandInSummary(summary, target);
+    if (!view) {
+        process.stderr.write(`Unknown command: ${target}\n`);
+        return 2;
+    }
+    // Attribute the hide/enable to a profile when one is active.
+    const hiddenByProfile = !!activeProfile?.hidden?.includes(target);
+    const enabledByProfile = !!activeProfile?.enabled?.includes(target);
+    if (json) {
+        process.stdout.write(asJson({
+            ...view,
+            activeProfile: activeProfile?.id ?? null,
+            hiddenByProfile,
+            enabledByProfile,
+        }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Surface — ${target}`));
+    process.stdout.write(kv('tier', view.tier) + '\n');
+    process.stdout.write(kv('source', view.source) + '\n');
+    if (view.detail)
+        process.stdout.write(kv('detail', view.detail) + '\n');
+    process.stdout.write(kv('callable', String(view.callable)) + '\n');
+    process.stdout.write(kv('visible-in-help', String(view.visibleInHelp)) + '\n');
+    process.stdout.write(kv('hidden-by-config', String(view.hidden)) + '\n');
+    process.stdout.write(kv('enabled-by-config', String(view.enabled)) + '\n');
+    if (view.pack)
+        process.stdout.write(kv('pack', view.pack) + '\n');
+    if (activeProfile) {
+        process.stdout.write(kv('active-profile', activeProfile.id + (activeProfile.pack ? ` (${activeProfile.pack})` : ' (builtin)')) + '\n');
+        if (hiddenByProfile)
+            process.stdout.write(kv('hidden-by-profile', 'yes — profile hides this from --help') + '\n');
+        if (enabledByProfile)
+            process.stdout.write(kv('enabled-by-profile', 'yes — profile turns this on') + '\n');
+    }
+    if (view.tier === CommandTier.Experimental && !view.callable) {
+        process.stdout.write('\nWhy gated: ' + (view.detail ?? 'experimental — opt-in required.') + '\n');
+        process.stdout.write('\nTo enable:\n');
+        process.stdout.write(`  $ shrk surface enable ${target} --write\n`);
+        if (activeProfile) {
+            process.stdout.write(`\nOr switch profile (current: ${activeProfile.id}):\n`);
+            process.stdout.write('  $ shrk surface profiles list\n');
+        }
+    }
+    else if (view.tier === CommandTier.Extended && view.hidden) {
+        const reason = hiddenByProfile
+            ? `Hidden by the active profile (${activeProfile?.id}).`
+            : 'Hidden by surface.hidden in sharkcraft.config.ts.';
+        process.stdout.write('\n' + reason + ' To restore visibility:\n');
+        process.stdout.write(`  $ shrk surface unhide ${target} --write\n`);
+    }
+    return 0;
+}
+async function runMutate({ cwd, json, write, target, op }) {
+    if (!target) {
+        process.stderr.write(`Usage: shrk surface ${op} <command> [--write]\n`);
+        return 2;
+    }
+    const { context, inspection } = await loadSurfaceContext({ cwd });
+    const summary = buildSurfaceSummary(context);
+    const view = findCommandInSummary(summary, target);
+    if (!view) {
+        process.stderr.write(`Unknown command: ${target}\n`);
+        return 2;
+    }
+    const refusal = refuseIfInvalid(op, view);
+    if (refusal) {
+        process.stderr.write(refusal + '\n');
+        return 2;
+    }
+    const edit = toEdit(op, target);
+    const configFile = inspection.configFile ?? defaultConfigFile(inspection.sharkcraftDir ?? `${cwd}/sharkcraft`);
+    const diff = planSurfaceEdit(configFile, context.surfaceConfig, [edit]);
+    if (json) {
+        process.stdout.write(asJson({ diff, willWrite: write }) + '\n');
+    }
+    else {
+        renderDiffText(diff, write);
+    }
+    if (!write)
+        return 0;
+    const result = applySurfaceEdit(diff);
+    if (!json) {
+        process.stdout.write(`\nWrote ${result.configFile} (${result.edits.length} edit${result.edits.length === 1 ? '' : 's'}).\n`);
+    }
+    return 0;
+}
+function refuseIfInvalid(op, view) {
+    if (view.tier === CommandTier.Core && (op === 'disable' || op === 'hide')) {
+        return `Cannot ${op} a core command (${view.command}).`;
+    }
+    if (op === 'hide' && view.tier === CommandTier.Experimental) {
+        return `Cannot hide an experimental command (${view.command}); use disable instead.`;
+    }
+    if (op === 'enable' && view.tier !== CommandTier.Experimental && !view.enabled) {
+        return `Refusing no-op: ${view.command} is not experimental (tier=${view.tier}).`;
+    }
+    if (op === 'disable' && !view.enabled) {
+        return `Refusing no-op: ${view.command} is not currently enabled.`;
+    }
+    if (op === 'unhide' && !view.hidden) {
+        return `Refusing no-op: ${view.command} is not currently hidden.`;
+    }
+    return null;
+}
+function toEdit(op, command) {
+    switch (op) {
+        case 'enable':
+            return { field: 'enabled', command, operation: 'add' };
+        case 'disable':
+            return { field: 'enabled', command, operation: 'remove' };
+        case 'hide':
+            return { field: 'hidden', command, operation: 'add' };
+        case 'unhide':
+            return { field: 'hidden', command, operation: 'remove' };
+    }
+}
+async function runReset({ cwd, json, write }) {
+    const { context, inspection } = await loadSurfaceContext({ cwd });
+    const edits = [];
+    for (const name of context.surfaceConfig?.enabled ?? []) {
+        edits.push({ field: 'enabled', command: name, operation: 'remove' });
+    }
+    for (const name of context.surfaceConfig?.hidden ?? []) {
+        edits.push({ field: 'hidden', command: name, operation: 'remove' });
+    }
+    const configFile = inspection.configFile ?? defaultConfigFile(inspection.sharkcraftDir ?? `${cwd}/sharkcraft`);
+    const diff = planSurfaceEdit(configFile, context.surfaceConfig, edits);
+    if (json) {
+        process.stdout.write(asJson({ diff, willWrite: write }) + '\n');
+    }
+    else {
+        renderDiffText(diff, write);
+    }
+    if (!write)
+        return 0;
+    applySurfaceEdit(diff);
+    if (!json)
+        process.stdout.write(`\nWrote ${diff.configFile} (reset).\n`);
+    return 0;
+}
+function renderDiffText(diff, willWrite) {
+    process.stdout.write(header('Surface config edit'));
+    process.stdout.write(kv('configFile', diff.configFile) + '\n');
+    process.stdout.write(kv('edits', String(diff.edits.length)) + '\n');
+    for (const edit of diff.edits) {
+        const sign = edit.operation === 'add' ? '+' : '-';
+        process.stdout.write(`  ${sign} surface.${edit.field}: ${edit.command}\n`);
+    }
+    if (!willWrite) {
+        process.stdout.write('\nDry run. Pass --write to apply.\n');
+    }
+}

package/dist/commands/task-context.command.d.ts

@@ -0,0 +1,7 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const understandTaskCommand: ICommandHandler;
+export declare const validateChangeCommand: ICommandHandler;
+export declare const contextBuildCommand: ICommandHandler;
+export declare const contextRefreshCommand: ICommandHandler;
+export declare const contextStatusCommand: ICommandHandler;
+//# sourceMappingURL=task-context.command.d.ts.map

package/dist/commands/task-context.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/task-context.command.ts"],"names":[],"mappings":"AAsBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAahC,eAAO,MAAM,qBAAqB,EAAE,eAyEnC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAmEnC,CAAC;AAIF,eAAO,MAAM,mBAAmB,EAAE,eA2DjC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAqBnC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAoBlC,CAAC"}