@shrkcrft/cli 0.1.0-alpha.2

package/dist/usage/usage-log.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Local-only command usage log. Writes one JSONL entry per
+ * command invocation to `.sharkcraft/usage/commands.jsonl`. Opt-out
+ * via `sharkcraft.config.ts usage.enabled = false` OR
+ * `SHARKCRAFT_USAGE_DISABLED=1`.
+ *
+ * Hard contracts:
+ *   - Local only. NEVER sent anywhere; no network code touches this file.
+ *   - Flag VALUES are never recorded. Only flag NAMES (the `--name`
+ *     part, with the `--` stripped).
+ *   - Rotates at 10MB to `commands.jsonl.1`; only one rotated file
+ *     kept (the previous .1 is overwritten).
+ *   - Append-only writes; failures degrade silently — the CLI must
+ *     never fail because the usage log couldn't be written.
+ */
+export declare const USAGE_LOG_SCHEMA = "sharkcraft.usage.v1";
+export declare const USAGE_LOG_DIR = ".sharkcraft/usage";
+export declare const USAGE_LOG_FILE = "commands.jsonl";
+export declare const USAGE_LOG_ROTATE_BYTES: number;
+export interface IUsageEntry {
+    schemaVersion: typeof USAGE_LOG_SCHEMA;
+    ts: string;
+    command: string;
+    exitCode: number;
+    durationMs: number;
+    /** Flag names (with leading `--` stripped). Never values. */
+    flags: readonly string[];
+}
+export interface IUsageRecordOptions {
+    cwd: string;
+    command: string;
+    exitCode: number;
+    durationMs: number;
+    flags: readonly string[];
+    /** When false (or env var set), the writer is a no-op. */
+    enabled: boolean;
+}
+export declare function recordUsage(opts: IUsageRecordOptions): void;
+/**
+ * Sanitize raw argv into flag NAMES only. Drops values, drops
+ * positional args, dedupes. Single-letter flags keep their dash.
+ *
+ * Examples:
+ *   `["doctor", "--json"]`              → `["--json"]`
+ *   `["task", "<task>", "--top", "5"]`  → `["--top"]`
+ *   `["--cwd=foo", "--debug"]`          → `["--cwd", "--debug"]`
+ */
+export declare function sanitizeFlagNames(rawArgv: readonly string[]): string[];
+/**
+ * Extract the leading command path (top-level + first
+ * subcommand if present, no flags) from raw argv.
+ */
+export declare function extractCommandPath(rawArgv: readonly string[]): string;
+//# sourceMappingURL=usage-log.d.ts.map

package/dist/usage/usage-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-log.d.ts","sourceRoot":"","sources":["../../src/usage/usage-log.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AACtD,eAAO,MAAM,aAAa,sBAAsB,CAAC;AACjD,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,sBAAsB,QAAmB,CAAC;AAEvD,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,OAAO,gBAAgB,CAAC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAqB3D;AAcD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAkBtE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAQrE"}

package/dist/usage/usage-log.js

@@ -0,0 +1,105 @@
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync, } from 'node:fs';
+import * as nodePath from 'node:path';
+/**
+ * Local-only command usage log. Writes one JSONL entry per
+ * command invocation to `.sharkcraft/usage/commands.jsonl`. Opt-out
+ * via `sharkcraft.config.ts usage.enabled = false` OR
+ * `SHARKCRAFT_USAGE_DISABLED=1`.
+ *
+ * Hard contracts:
+ *   - Local only. NEVER sent anywhere; no network code touches this file.
+ *   - Flag VALUES are never recorded. Only flag NAMES (the `--name`
+ *     part, with the `--` stripped).
+ *   - Rotates at 10MB to `commands.jsonl.1`; only one rotated file
+ *     kept (the previous .1 is overwritten).
+ *   - Append-only writes; failures degrade silently — the CLI must
+ *     never fail because the usage log couldn't be written.
+ */
+export const USAGE_LOG_SCHEMA = 'sharkcraft.usage.v1';
+export const USAGE_LOG_DIR = '.sharkcraft/usage';
+export const USAGE_LOG_FILE = 'commands.jsonl';
+export const USAGE_LOG_ROTATE_BYTES = 10 * 1024 * 1024;
+export function recordUsage(opts) {
+    if (!opts.enabled)
+        return;
+    if (process.env.SHARKCRAFT_USAGE_DISABLED === '1')
+        return;
+    const dir = nodePath.join(opts.cwd, USAGE_LOG_DIR);
+    const file = nodePath.join(dir, USAGE_LOG_FILE);
+    const entry = {
+        schemaVersion: USAGE_LOG_SCHEMA,
+        ts: new Date().toISOString(),
+        command: opts.command,
+        exitCode: opts.exitCode,
+        durationMs: Math.max(0, Math.round(opts.durationMs)),
+        flags: opts.flags,
+    };
+    try {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        rotateIfTooBig(file);
+        appendFileSync(file, JSON.stringify(entry) + '\n', 'utf8');
+    }
+    catch {
+        // Silent. The CLI must never fail because of the usage log.
+    }
+}
+function rotateIfTooBig(file) {
+    if (!existsSync(file))
+        return;
+    try {
+        const size = statSync(file).size;
+        if (size < USAGE_LOG_ROTATE_BYTES)
+            return;
+        const rotated = `${file}.1`;
+        renameSync(file, rotated);
+    }
+    catch {
+        // ignore
+    }
+}
+/**
+ * Sanitize raw argv into flag NAMES only. Drops values, drops
+ * positional args, dedupes. Single-letter flags keep their dash.
+ *
+ * Examples:
+ *   `["doctor", "--json"]`              → `["--json"]`
+ *   `["task", "<task>", "--top", "5"]`  → `["--top"]`
+ *   `["--cwd=foo", "--debug"]`          → `["--cwd", "--debug"]`
+ */
+export function sanitizeFlagNames(rawArgv) {
+    const out = new Set();
+    for (let i = 0; i < rawArgv.length; i += 1) {
+        const t = rawArgv[i];
+        if (t.startsWith('--')) {
+            const eq = t.indexOf('=');
+            const name = eq === -1 ? t : t.slice(0, eq);
+            out.add(name);
+            // If the flag took the NEXT positional as its value, skip it.
+            if (eq === -1) {
+                const next = rawArgv[i + 1];
+                if (next !== undefined && !next.startsWith('-'))
+                    i += 1;
+            }
+        }
+        else if (t.startsWith('-') && t.length > 1) {
+            out.add(t);
+        }
+    }
+    return [...out].sort();
+}
+/**
+ * Extract the leading command path (top-level + first
+ * subcommand if present, no flags) from raw argv.
+ */
+export function extractCommandPath(rawArgv) {
+    const tokens = [];
+    for (const t of rawArgv) {
+        if (t.startsWith('-'))
+            break;
+        if (tokens.length >= 2)
+            break;
+        tokens.push(t);
+    }
+    return tokens.join(' ');
+}

package/dist/validation/run-validation-loop.d.ts

@@ -0,0 +1,38 @@
+export interface IValidationCommandResult {
+    command: string;
+    passed: boolean;
+    note?: string;
+}
+export interface IRunValidationLoopOptions {
+    cwd: string;
+    /** Explicit shell command (--command). Always treated as trusted. */
+    explicitCommand?: string;
+    /** Verification ids selected via repeated --verification flags. */
+    verificationIds: readonly string[];
+    /** When true, run every trusted verification command defined in config. */
+    allVerifications: boolean;
+    /** Pack-contributed commands are never auto-run; this is a future opt-in. */
+    allowPackCommands: boolean;
+    /** When set, validation report is written here as JSON. */
+    reportDir: string | null;
+    /** Optional filename for the report (default: timestamped). */
+    reportFileName?: string;
+    /** Optional callback when a command starts running (for progress output). */
+    onCommandStart?: (label: string) => void;
+}
+export interface IRunValidationLoopResult {
+    passed: boolean;
+    warnings: number;
+    commandsRun: IValidationCommandResult[];
+    commandsFailed: string[];
+    boundaryViolations: number;
+    reportPath?: string;
+}
+/**
+ * Run a set of verification commands defined in `sharkcraft.config.ts` plus an
+ * optional explicit `--command`, then perform a non-fatal boundary scan. Writes
+ * a JSON report when `reportDir` is set. Pure side effects: spawns shells the
+ * caller asked for; never invents commands from pack contributions.
+ */
+export declare function runValidationLoop(options: IRunValidationLoopOptions): Promise<IRunValidationLoopResult>;
+//# sourceMappingURL=run-validation-loop.d.ts.map

package/dist/validation/run-validation-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-validation-loop.d.ts","sourceRoot":"","sources":["../../src/validation/run-validation-loop.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,2EAA2E;IAC3E,gBAAgB,EAAE,OAAO,CAAC;IAC1B,6EAA6E;IAC7E,iBAAiB,EAAE,OAAO,CAAC;IAC3B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1C;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,wBAAwB,EAAE,CAAC;IACxC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAqGnC"}

package/dist/validation/run-validation-loop.js

@@ -0,0 +1,100 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+/**
+ * Run a set of verification commands defined in `sharkcraft.config.ts` plus an
+ * optional explicit `--command`, then perform a non-fatal boundary scan. Writes
+ * a JSON report when `reportDir` is set. Pure side effects: spawns shells the
+ * caller asked for; never invents commands from pack contributions.
+ */
+export async function runValidationLoop(options) {
+    const out = {
+        passed: true,
+        warnings: 0,
+        commandsRun: [],
+        commandsFailed: [],
+        boundaryViolations: 0,
+    };
+    const commands = [];
+    if (options.explicitCommand) {
+        commands.push({ command: options.explicitCommand, trusted: true });
+    }
+    try {
+        const { loadProjectConfig } = await import('@shrkcrft/config');
+        const cfgResult = await loadProjectConfig(options.cwd);
+        const cfg = cfgResult.ok ? cfgResult.value.config : null;
+        const ver = cfg?.verificationCommands ?? [];
+        const wantIds = new Set(options.verificationIds);
+        for (const v of ver) {
+            const shouldRun = options.allVerifications || wantIds.has(v.id);
+            if (!shouldRun)
+                continue;
+            commands.push({ id: v.id, command: v.command, trusted: v.trusted !== false });
+        }
+        const knownIds = new Set(ver.map((v) => v.id));
+        for (const id of options.verificationIds) {
+            if (!knownIds.has(id)) {
+                out.commandsRun.push({
+                    command: `--verification ${id}`,
+                    passed: false,
+                    note: `unknown verification id "${id}" — define it in sharkcraft.config.ts verificationCommands[]`,
+                });
+                out.commandsFailed.push(`--verification ${id}`);
+                out.passed = false;
+            }
+        }
+    }
+    catch {
+        // Best-effort: a missing config just means no configured commands.
+    }
+    void options.allowPackCommands;
+    if (commands.length === 0 && options.verificationIds.length === 0 && !options.explicitCommand) {
+        out.commandsRun.push({
+            command: '(no command supplied)',
+            passed: true,
+            note: 'pass --command "<shell>", --verification <id>, or --all-verifications. ' +
+                'Define verificationCommands[] in sharkcraft.config.ts.',
+        });
+    }
+    for (const entry of commands) {
+        const { spawnSync } = await import('node:child_process');
+        const label = entry.id ? `${entry.id}: ${entry.command}` : entry.command;
+        options.onCommandStart?.(label);
+        const res = spawnSync(entry.command, [], {
+            cwd: options.cwd,
+            shell: true,
+            stdio: ['ignore', 'inherit', 'inherit'],
+        });
+        const ok = res.status === 0;
+        out.commandsRun.push({ command: label, passed: ok });
+        if (!ok) {
+            out.commandsFailed.push(label);
+            out.passed = false;
+        }
+    }
+    // Boundary scan as a non-fatal warning (mirrors `shrk apply --validate`).
+    try {
+        const { inspectSharkcraft } = await import('@shrkcrft/inspector');
+        const { evaluateBoundaries, scanImports } = await import('@shrkcrft/boundaries');
+        const inspection = await inspectSharkcraft({ cwd: options.cwd });
+        if (inspection.boundaryRegistry.size() > 0) {
+            const scan = scanImports({ projectRoot: options.cwd });
+            const evalResult = evaluateBoundaries(scan, inspection.boundaryRegistry.list());
+            out.boundaryViolations = evalResult.violations.length;
+            out.warnings += evalResult.counts.warning;
+            if (evalResult.counts.error > 0)
+                out.passed = false;
+        }
+    }
+    catch {
+        // boundary scan is best-effort.
+    }
+    if (options.reportDir) {
+        if (!existsSync(options.reportDir))
+            mkdirSync(options.reportDir, { recursive: true });
+        const filename = options.reportFileName ?? `validate-${new Date().toISOString().replace(/[:.]/g, '-')}.json`;
+        const path = nodePath.join(options.reportDir, filename);
+        writeFileSync(path, JSON.stringify(out, null, 2) + '\n', 'utf8');
+        out.reportPath = path;
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@shrkcrft/cli",
+  "version": "0.1.0-alpha.2",
+  "description": "SharkCraft CLI (`shrk`): structured project intelligence for AI coding agents.",
+  "license": "MIT",
+  "author": "SharkCraft contributors",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "shrk": "./dist/main.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shrkcrft/sharkcraft.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/shrkcrft/sharkcraft",
+  "bugs": {
+    "url": "https://github.com/shrkcrft/sharkcraft/issues"
+  },
+  "keywords": [
+    "sharkcraft",
+    "cli",
+    "shrk",
+    "ai-agent",
+    "mcp"
+  ],
+  "engines": {
+    "bun": ">=1.1.0",
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@shrkcrft/core": "^0.1.0-alpha.2",
+    "@shrkcrft/config": "^0.1.0-alpha.2",
+    "@shrkcrft/workspace": "^0.1.0-alpha.2",
+    "@shrkcrft/knowledge": "^0.1.0-alpha.2",
+    "@shrkcrft/context": "^0.1.0-alpha.2",
+    "@shrkcrft/rules": "^0.1.0-alpha.2",
+    "@shrkcrft/paths": "^0.1.0-alpha.2",
+    "@shrkcrft/templates": "^0.1.0-alpha.2",
+    "@shrkcrft/plugin-api": "^0.1.0-alpha.2",
+    "@shrkcrft/dashboard-api": "^0.1.0-alpha.2",
+    "@shrkcrft/pipelines": "^0.1.0-alpha.2",
+    "@shrkcrft/presets": "^0.1.0-alpha.2",
+    "@shrkcrft/boundaries": "^0.1.0-alpha.2",
+    "@shrkcrft/generator": "^0.1.0-alpha.2",
+    "@shrkcrft/importer": "^0.1.0-alpha.2",
+    "@shrkcrft/inspector": "^0.1.0-alpha.2",
+    "@shrkcrft/ai": "^0.1.0-alpha.2",
+    "@shrkcrft/shared": "^0.1.0-alpha.2",
+    "@shrkcrft/mcp-server": "^0.1.0-alpha.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}