@shrkcrft/cli 0.1.0-alpha.2

package/dist/commands/init.command.js

@@ -0,0 +1,301 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { detectProjectRoot, inspectWorkspace } from '@shrkcrft/workspace';
+import { applyPresetPlan, BUILTIN_PRESETS, PresetRegistry, previewPresetApplication, recommendPresets } from '@shrkcrft/presets';
+import { listBuiltInSurfaceProfiles, suggestSurfaceProfile } from '@shrkcrft/inspector';
+import { INIT_FILES } from "../init/init-templates.js";
+import { buildDetectedBlock, renderDetectedBlockText } from "../init/detected-block.js";
+import { ensureSharkcraftGitignore, renderGitignorePatch } from "../init/gitignore.js";
+import { applySurfaceTextEdit } from "../surface/surface-config-writer.js";
+import { flagBool, flagString, resolveCwd } from "../command-registry.js";
+import { bullet, header } from "../output/format-output.js";
+const LEGACY_PRESET_ID = 'legacy-init';
+async function resolveSurfaceProfile(cwd, override) {
+    if (override) {
+        const all = listBuiltInSurfaceProfiles();
+        if (!all.includes(override)) {
+            throw new Error(`Unknown --surface-profile "${override}". Choose one of: ${all.join(', ')}.`);
+        }
+        return {
+            profile: override,
+            reason: 'explicit --surface-profile override.',
+            source: 'override',
+        };
+    }
+    const ws = await inspectWorkspace({ startDir: cwd });
+    const sug = suggestSurfaceProfile(ws.profiles);
+    return {
+        profile: sug.profile,
+        reason: sug.reason,
+        source: 'detected',
+    };
+}
+/**
+ * Inject the chosen surface profile into the generated
+ * `sharkcraft.config.ts`. Idempotent: if a `surface:` block already
+ * names the same profile, the file is left untouched.
+ */
+function injectSurfaceProfile(sharkcraftDir, decision) {
+    const configFile = nodePath.join(sharkcraftDir, 'sharkcraft.config.ts');
+    if (!existsSync(configFile)) {
+        return { written: false, configFile, alreadyMatched: false };
+    }
+    const original = readFileSync(configFile, 'utf8');
+    const profileRegex = /profile\s*:\s*['"]([^'"]+)['"]/m;
+    const existing = profileRegex.exec(original);
+    if (existing && existing[1] === decision.profile) {
+        return { written: false, configFile, alreadyMatched: true };
+    }
+    const updated = applySurfaceTextEdit(original, {
+        profile: decision.profile,
+        enabled: [],
+        hidden: [],
+    });
+    const comment = `// surface.profile picked by \`shrk init\` (${decision.source}): ${decision.reason}\n`;
+    // Insert the comment immediately above the surface block so it survives
+    // re-writes of the surface block itself.
+    const final = updated.replace(/(^\s*surface\s*:\s*\{)/m, `${comment}$1`);
+    writeFileSync(configFile, final, 'utf8');
+    return { written: true, configFile, alreadyMatched: false };
+}
+async function pickAutoPreset(cwd) {
+    const ws = await inspectWorkspace({ startDir: cwd });
+    const recs = recommendPresets([...BUILTIN_PRESETS], {
+        profiles: ws.profiles,
+        limit: 1,
+    });
+    const top = recs[0];
+    if (!top) {
+        return { presetId: 'generic', profiles: ws.profiles, reasons: ['no high-signal preset matched; fell back to generic'] };
+    }
+    return { presetId: top.preset.id, profiles: ws.profiles, reasons: top.reasons };
+}
+async function applyPresetInit(cwd, mode) {
+    const registry = new PresetRegistry([...BUILTIN_PRESETS]);
+    const preset = registry.get(mode.presetId);
+    if (!preset) {
+        process.stderr.write(`Unknown preset: ${mode.presetId}. Run \`shrk presets list\` to see options.\n`);
+        return 1;
+    }
+    const plan = previewPresetApplication(preset, {
+        projectRoot: cwd,
+        force: mode.force,
+        merge: mode.merge,
+    });
+    if (mode.dryRun) {
+        process.stdout.write(header('SharkCraft init — dry-run'));
+        process.stdout.write(`Preset: ${preset.id} — ${preset.title}\n`);
+        process.stdout.write(`Folder: ${plan.sharkcraftDir}\n`);
+        if (mode.showDetectedProfiles) {
+            try {
+                const ws = await inspectWorkspace({ startDir: cwd });
+                process.stdout.write(`Detected profiles: ${ws.profiles.join(', ') || '(none)'}\n`);
+                // Include the structured Detected block so the user sees
+                // exactly what was detected vs. what was guessed/inferred.
+                const detected = buildDetectedBlock(cwd, ws);
+                process.stdout.write(header('Detected'));
+                process.stdout.write(renderDetectedBlockText(detected) + '\n');
+            }
+            catch {
+                // best-effort; do not fail dry-run on inspect errors
+            }
+        }
+        process.stdout.write('\nWould write:\n');
+        for (const entry of plan.entries) {
+            process.stdout.write(bullet(`[${entry.status}] ${entry.relPath}`) + '\n');
+        }
+        for (const warn of plan.warnings) {
+            process.stdout.write(bullet(`(warning) ${warn}`) + '\n');
+        }
+        process.stdout.write('\nNext:\n');
+        for (const cmd of preset.recommendedNextCommands ?? [
+            'shrk init --zero-config --write',
+            'shrk doctor',
+            'shrk context --task "<task>"',
+        ]) {
+            process.stdout.write(bullet(`$ ${cmd}`) + '\n');
+        }
+        if (!mode.skipGitignore) {
+            const patch = ensureSharkcraftGitignore({ cwd, dryRun: true });
+            process.stdout.write('\n' + renderGitignorePatch(patch, true));
+        }
+        process.stdout.write('\nRun with --write to persist.\n');
+        return 0;
+    }
+    const result = applyPresetPlan(plan);
+    // Inject the surface profile into the generated config so the
+    // user starts from a sensible default rather than the empty fallback.
+    let surfaceProfileResult = null;
+    if (mode.surfaceProfile) {
+        surfaceProfileResult = injectSurfaceProfile(plan.sharkcraftDir, {
+            profile: mode.surfaceProfile,
+            reason: mode.surfaceProfileReason ?? 'configured by init.',
+            source: 'override',
+        });
+    }
+    process.stdout.write(header('SharkCraft initialized'));
+    process.stdout.write(`Preset: ${preset.id} — ${preset.title}\n`);
+    process.stdout.write(`Folder: ${plan.sharkcraftDir}\n`);
+    if (surfaceProfileResult) {
+        if (surfaceProfileResult.written) {
+            process.stdout.write(`Surface profile: ${mode.surfaceProfile} (written to sharkcraft.config.ts)\n`);
+        }
+        else if (surfaceProfileResult.alreadyMatched) {
+            process.stdout.write(`Surface profile: ${mode.surfaceProfile} (already set; no change)\n`);
+        }
+    }
+    if (mode.showDetectedProfiles) {
+        try {
+            const ws = await inspectWorkspace({ startDir: cwd });
+            process.stdout.write(`Detected profiles: ${ws.profiles.join(', ') || '(none)'}\n`);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    if (result.written.length) {
+        process.stdout.write('\nCreated files:\n');
+        for (const p of result.written)
+            process.stdout.write(bullet(p) + '\n');
+    }
+    if (result.skipped.length) {
+        process.stdout.write('\nSkipped (already exist; use --force to overwrite):\n');
+        for (const p of result.skipped)
+            process.stdout.write(bullet(p) + '\n');
+    }
+    if (!mode.skipGitignore) {
+        const patch = ensureSharkcraftGitignore({ cwd, dryRun: false });
+        if (patch.added.length > 0) {
+            process.stdout.write('\n' + renderGitignorePatch(patch, false));
+        }
+    }
+    process.stdout.write('\nNext:\n');
+    for (const cmd of preset.recommendedNextCommands ?? [
+        'shrk doctor',
+        'shrk context --task "<task>"',
+    ]) {
+        process.stdout.write(bullet(`$ ${cmd}`) + '\n');
+    }
+    process.stdout.write(bullet('Start the MCP server: `shrk mcp serve` (or run it via Claude Code)') + '\n');
+    return 0;
+}
+function applyLegacyInit(cwd, force) {
+    const { root } = detectProjectRoot(cwd);
+    const sharkcraftDir = nodePath.join(root, 'sharkcraft');
+    if (existsSync(sharkcraftDir) && !force) {
+        process.stderr.write(`sharkcraft/ already exists at ${sharkcraftDir}. Use --force to overwrite individual files.\n`);
+        return 1;
+    }
+    mkdirSync(sharkcraftDir, { recursive: true });
+    const created = [];
+    const skipped = [];
+    for (const file of INIT_FILES) {
+        const fullPath = nodePath.join(sharkcraftDir, file.relativePath);
+        mkdirSync(nodePath.dirname(fullPath), { recursive: true });
+        if (existsSync(fullPath) && !force) {
+            skipped.push(file.relativePath);
+            continue;
+        }
+        writeFileSync(fullPath, file.content, 'utf8');
+        created.push(file.relativePath);
+    }
+    process.stdout.write(header('SharkCraft initialized'));
+    process.stdout.write(`Preset: ${LEGACY_PRESET_ID} (full seed)\n`);
+    process.stdout.write(`Folder: ${sharkcraftDir}\n`);
+    if (created.length) {
+        process.stdout.write('\nCreated files:\n');
+        for (const c of created)
+            process.stdout.write(bullet(c) + '\n');
+    }
+    if (skipped.length) {
+        process.stdout.write('\nSkipped (already exist; use --force to overwrite):\n');
+        for (const s of skipped)
+            process.stdout.write(bullet(s) + '\n');
+    }
+    process.stdout.write('\nNext:\n');
+    process.stdout.write(bullet('Run `shrk inspect` to see your project summary.') + '\n');
+    process.stdout.write(bullet('Run `shrk knowledge list` to see what was seeded.') + '\n');
+    process.stdout.write(bullet('Customize sharkcraft/rules.ts, paths.ts, templates.ts.') + '\n');
+    return 0;
+}
+export const initCommand = {
+    name: 'init',
+    description: 'Initialize a sharkcraft/ folder in the current repository. Pass --preset <id> to apply a built-in preset (default: generic). Use --zero-config or --preset auto to detect the workspace and pick a preset automatically. Use --legacy for the full pre-preset seed.',
+    usage: 'shrk init [--preset <id|auto>] [--zero-config] [--dry-run] [--write] [--legacy] [--force] [--merge] [--suggest-only] [--no-gitignore] [--surface-profile <id>]',
+    async run(args) {
+        const force = flagBool(args, 'force');
+        const merge = flagBool(args, 'merge');
+        const cwd = resolveCwd(args);
+        const skipGitignore = flagBool(args, 'no-gitignore');
+        if (flagBool(args, 'legacy')) {
+            const code = applyLegacyInit(cwd, force);
+            if (code === 0 && !skipGitignore) {
+                const patch = ensureSharkcraftGitignore({ cwd, dryRun: false });
+                if (patch.added.length > 0) {
+                    process.stdout.write('\n' + renderGitignorePatch(patch, false));
+                }
+            }
+            return code;
+        }
+        // Suggest-only mode: detect profiles + print recommendations, do nothing else.
+        if (flagBool(args, 'suggest-only')) {
+            const ws = await inspectWorkspace({ startDir: cwd });
+            const recs = recommendPresets([...BUILTIN_PRESETS], { profiles: ws.profiles });
+            process.stdout.write(header('Suggested presets'));
+            process.stdout.write(`Detected profiles: ${ws.profiles.join(', ') || '(none)'}\n\n`);
+            for (const r of recs) {
+                process.stdout.write(`  ${r.preset.id.padEnd(22)} ${r.confidence.padEnd(6)} ${r.preset.title}\n`);
+            }
+            return 0;
+        }
+        const rawPreset = flagString(args, 'preset');
+        const zeroConfig = flagBool(args, 'zero-config');
+        const isAuto = zeroConfig || rawPreset === 'auto';
+        let presetId;
+        let showDetected = false;
+        if (isAuto) {
+            const picked = await pickAutoPreset(cwd);
+            presetId = picked.presetId;
+            showDetected = true;
+            process.stdout.write(header('Zero-config preset selection'));
+            process.stdout.write(`Detected profiles: ${picked.profiles.join(', ') || '(none)'}\n`);
+            process.stdout.write(`Picked preset: ${presetId}\n`);
+            if (picked.reasons.length) {
+                process.stdout.write('Reasons:\n');
+                for (const r of picked.reasons)
+                    process.stdout.write(bullet(r) + '\n');
+            }
+            process.stdout.write('\n');
+        }
+        else {
+            presetId = rawPreset ?? 'generic';
+        }
+        // Dry-run default for zero-config; explicit --dry-run also wins.
+        const dryRunFlag = flagBool(args, 'dry-run');
+        const writeFlag = flagBool(args, 'write');
+        const dryRun = (isAuto && !writeFlag) || (dryRunFlag && !writeFlag);
+        // Surface profile detection / override.
+        const surfaceProfileFlag = flagString(args, 'surface-profile');
+        let surfaceDecision = null;
+        try {
+            surfaceDecision = await resolveSurfaceProfile(cwd, surfaceProfileFlag ?? undefined);
+        }
+        catch (e) {
+            process.stderr.write(`${e.message}\n`);
+            return 2;
+        }
+        if (dryRun) {
+            process.stdout.write(`Surface profile: ${surfaceDecision.profile} (${surfaceDecision.source}) — ${surfaceDecision.reason}\n`);
+        }
+        return applyPresetInit(cwd, {
+            presetId,
+            dryRun,
+            force,
+            merge,
+            showDetectedProfiles: showDetected,
+            skipGitignore,
+            surfaceProfile: surfaceDecision.profile,
+            surfaceProfileReason: surfaceDecision.reason,
+        });
+    },
+};

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

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

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

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

package/dist/commands/inspect.command.js

@@ -0,0 +1,122 @@
+import { inspectSharkcraft, buildProjectOverview, renderOverviewText } from '@shrkcrft/inspector';
+import { flagBool, flagNumber, resolveCwd, } from "../command-registry.js";
+import { asJson, bullet, header, kv } from "../output/format-output.js";
+import { buildDetectedBlock, renderDetectedBlockText } from "../init/detected-block.js";
+export const inspectCommand = {
+    name: 'inspect',
+    description: 'Inspect the current repository (project, frameworks, package manager, sharkcraft setup). Prints a Detected block so a brand-new user can see what zero-config init would do. `--no-config` tolerates a missing sharkcraft/ folder without warnings. `--debug` emits per-loader timing/status; `--no-cache` bypasses the persistent loader cache; `--loader-timeout <ms>` bounds each TS-asset import.',
+    usage: 'shrk [--cwd <dir>] inspect [--no-config] [--json] [--debug] [--no-cache] [--loader-timeout <ms>]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const noConfig = flagBool(args, 'no-config');
+        const noCache = flagBool(args, 'no-cache');
+        const debug = flagBool(args, 'debug');
+        const loaderTimeout = flagNumber(args, 'loader-timeout');
+        const inspectOpts = {
+            cwd,
+            useCache: !noCache,
+        };
+        if (typeof loaderTimeout === 'number' && loaderTimeout > 0) {
+            inspectOpts.loaderTimeoutMs = loaderTimeout;
+        }
+        const inspection = await inspectSharkcraft(inspectOpts);
+        const overview = buildProjectOverview(inspection.workspace, inspection.config?.projectName);
+        const detected = buildDetectedBlock(cwd, inspection.workspace);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({
+                targetRoot: inspection.projectRoot,
+                overview,
+                workspace: {
+                    projectRoot: inspection.workspace.projectRoot,
+                    packageManager: inspection.workspace.packageManager,
+                    frameworks: inspection.workspace.frameworks,
+                    hasTypeScript: inspection.workspace.hasTypeScript,
+                    scripts: Object.keys(inspection.workspace.scripts),
+                },
+                detected,
+                noConfig,
+                sharkcraft: {
+                    hasFolder: inspection.hasSharkcraftFolder,
+                    configFile: inspection.configFile,
+                    sharkcraftDir: inspection.sharkcraftDir,
+                    knowledgeCount: inspection.knowledgeEntries.length,
+                    ruleCount: inspection.ruleService.list().length,
+                    pathCount: inspection.pathService.list().length,
+                    templateCount: inspection.templates.length,
+                },
+                loader: {
+                    inspectionElapsedMs: inspection.inspectionElapsedMs,
+                    cacheEnabled: inspection.cacheEnabled,
+                    cacheDir: inspection.cacheDir,
+                    diagnostics: inspection.loaderDiagnostics,
+                },
+            }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header('Target'));
+        process.stdout.write(kv('root', inspection.projectRoot) + '\n');
+        process.stdout.write(header('Project'));
+        process.stdout.write(renderOverviewText(overview) + '\n');
+        process.stdout.write(header('Package manager'));
+        process.stdout.write(kv('manager', inspection.workspace.packageManager.manager) + '\n');
+        if (inspection.workspace.packageManager.version) {
+            process.stdout.write(kv('version', inspection.workspace.packageManager.version) + '\n');
+        }
+        if (inspection.workspace.packageManager.evidence.length) {
+            process.stdout.write(kv('evidence', inspection.workspace.packageManager.evidence.join(', ')) + '\n');
+        }
+        if (inspection.workspace.frameworks.length) {
+            process.stdout.write(header('Frameworks'));
+            for (const f of inspection.workspace.frameworks) {
+                process.stdout.write(bullet(`${f.name}${f.version ? ` (${f.version})` : ''}`) + '\n');
+            }
+        }
+        process.stdout.write(header('Detected'));
+        process.stdout.write(renderDetectedBlockText(detected) + '\n');
+        process.stdout.write(header('SharkCraft setup'));
+        process.stdout.write(kv('folder', inspection.sharkcraftDir ?? '(missing)') + '\n');
+        process.stdout.write(kv('config', inspection.configFile ?? '(none)') + '\n');
+        process.stdout.write(kv('knowledge entries', inspection.knowledgeEntries.length) + '\n');
+        process.stdout.write(kv('rules', inspection.ruleService.list().length) + '\n');
+        process.stdout.write(kv('path conventions', inspection.pathService.list().length) + '\n');
+        process.stdout.write(kv('templates', inspection.templates.length) + '\n');
+        // Under --no-config, downgrade missing-sharkcraft warnings so the
+        // small-repo experience is friendly. Filter out the canonical "no
+        // sharkcraft/" warning the inspector emits when the folder is absent.
+        const warningsToShow = noConfig
+            ? inspection.warnings.filter((w) => !/sharkcraft.*not found|sharkcraft.*missing|no\s+sharkcraft/i.test(w))
+            : inspection.warnings;
+        if (warningsToShow.length) {
+            process.stdout.write(header('Warnings'));
+            for (const w of warningsToShow)
+                process.stdout.write(bullet(w) + '\n');
+        }
+        // Surface failed/timed-out/slow loaders outside of --debug so the
+        // user is not silently flying blind when a pack asset fails to load.
+        const problematic = inspection.loaderDiagnostics.filter((d) => d.status !== 'ok' || d.slow);
+        if (problematic.length > 0) {
+            process.stdout.write(header('Loader diagnostics'));
+            for (const d of problematic) {
+                process.stdout.write(bullet(`${d.kind} ${d.status} ${d.elapsedMs}ms ${d.filePath}${d.errorMessage ? ' — ' + d.errorMessage : ''}${d.suggestedNextCommand ? ' (try: ' + d.suggestedNextCommand + ')' : ''}`) + '\n');
+            }
+        }
+        if (debug) {
+            process.stdout.write(header('Loader timing (--debug)'));
+            process.stdout.write(kv('inspection elapsed', `${inspection.inspectionElapsedMs}ms`) + '\n');
+            process.stdout.write(kv('cache', inspection.cacheEnabled ? `on (${inspection.cacheDir})` : 'off') + '\n');
+            process.stdout.write(kv('loader entries', inspection.loaderDiagnostics.length) + '\n');
+            for (const d of inspection.loaderDiagnostics) {
+                process.stdout.write(`  ${d.kind.padEnd(10)} ${d.status.padEnd(12)} ${String(d.elapsedMs).padStart(5)}ms count=${d.count}${d.deduped ? ' (deduped)' : ''}${d.largeFile ? ' (large)' : ''}  ${d.filePath}\n`);
+                if (d.errorMessage)
+                    process.stdout.write(`      error: ${d.errorMessage}\n`);
+            }
+        }
+        if (!inspection.hasSharkcraftFolder) {
+            process.stdout.write('\nNo sharkcraft/ folder yet. Next: `shrk init --zero-config` to preview a preset based on detection above.\n');
+        }
+        else {
+            process.stdout.write('\nNext: run `shrk doctor` to validate setup, then `shrk context --task "<task>"`.\n');
+        }
+        return 0;
+    },
+};

package/dist/commands/knowledge-author.command.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Knowledge authoring CLI surface.
+ *
+ *   - `shrk knowledge add` — preview a new knowledge entry.
+ *   - `shrk knowledge update <id>` — preview an incremental change.
+ *   - `shrk knowledge remove <id>` — preview a removal (refuses if
+ *     reverse references exist unless --force-preview).
+ *   - `shrk knowledge author preview` — alias that classifies the
+ *     operation by which flags were passed.
+ *   - `shrk knowledge lint [--fix-preview]` — classify findings.
+ *
+ * All commands default to preview-only. Files land under
+ * `.sharkcraft/authoring/` (drafts) or `.sharkcraft/fixes/` (lint output).
+ * No direct mutation of `sharkcraft/knowledge.ts` or pack source.
+ */
+import { type ICommandHandler } from '../command-registry.js';
+export declare const knowledgeAddCommand: ICommandHandler;
+export declare const knowledgeUpdateCommand: ICommandHandler;
+export declare const knowledgeRemoveCommand: ICommandHandler;
+export declare const knowledgeLintCommand: ICommandHandler;
+export declare const knowledgeAuthorPreviewCommand: ICommandHandler;
+//# sourceMappingURL=knowledge-author.command.d.ts.map

package/dist/commands/knowledge-author.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-author.command.d.ts","sourceRoot":"","sources":["../../src/commands/knowledge-author.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAoBH,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAwChC,eAAO,MAAM,mBAAmB,EAAE,eAgEjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0GpC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAoEpC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eA2DlC,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,eAmB3C,CAAC"}