@ashlr/hub 2.2.0

package/dist/core/learn/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/core/learn/store.ts"],"names":[],"mappings":"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"}

package/dist/core/learn/tuning.d.ts

@@ -0,0 +1,48 @@
+/**
+ * tuning.ts — M26 PROPOSAL-ONLY routing/policy/prompt tuning suggestions.
+ *
+ * Derives tuning suggestions from a deterministic ReflectionReport and — only
+ * when explicitly asked — routes them to the M23 Approval Inbox as PENDING
+ * proposals. It NEVER auto-applies anything.
+ *
+ * HARD SAFETY INVARIANTS (M26) — paramount:
+ *  - PROPOSAL-ONLY. The ONLY sink is the inbox via createProposal (status
+ *    pending). There is NO code path here that writes the global config path,
+ *    saves config, or mutates routing policy or prompts. Suggestions reason
+ *    ABOUT routing but never change it. Each proposal is kind 'note' (a no-op
+ *    record that, even when applied, mutates nothing).
+ *  - DETERMINISTIC. deriveTuning() is pure over the report — no LLM, no network.
+ *  - NO OUTWARD ACTION. Proposals sit pending; nothing is shipped or deployed.
+ *  - BOUNDED. Caps the number of suggestions emitted.
+ *  - NEVER THROWS. Degrades to [] / a no-op emit.
+ *
+ * METADATA ONLY — proposals carry titles + rationale grounded in metrics; never
+ * secret values, never raw payloads.
+ */
+import type { Proposal, ReflectionReport, TuningProposal } from '../types.js';
+/**
+ * Derive PROPOSAL-ONLY tuning suggestions from a ReflectionReport. Pure over
+ * the report; never throws; never mutates anything; makes ZERO I/O or network
+ * calls. Returns at most MAX_TUNING suggestions, highest-confidence first.
+ *
+ * Heuristics (deterministic, grounded in report metrics):
+ *  - High localShare + zero cloud spend     -> "raise local-first threshold".
+ *  - A recurring failure cluster            -> "add a playbook for failure Y".
+ *  - A category succeeding ~every time      -> "lower retry cap for category X".
+ *  - A category far costlier than the fleet -> "flag over-budget category X".
+ *  - Effectiveness regressed vs prior        -> "review recent routing/policy".
+ *
+ * NOTE: every suggestion only DESCRIBES a possible change. Nothing here applies
+ * it — emitTuningProposals() routes them to the inbox as inert pending notes.
+ */
+export declare function deriveTuning(report: ReflectionReport): TuningProposal[];
+/**
+ * Convert derived TuningProposals into PENDING M23 inbox proposals via
+ * createProposal(). Returns the created Proposal records.
+ *
+ * GUARDRAIL: this is the ONLY outward sink for tuning. Each proposal is created
+ * with kind 'note' (a no-op record — applying it mutates NOTHING), origin
+ * 'manual', repo null, status 'pending'. There is NO path here that touches the
+ * global config, routing policy, or prompts. Never throws.
+ */
+export declare function emitTuningProposals(suggestions: TuningProposal[]): Proposal[];

package/dist/core/learn/tuning.js

@@ -0,0 +1,201 @@
+/**
+ * tuning.ts — M26 PROPOSAL-ONLY routing/policy/prompt tuning suggestions.
+ *
+ * Derives tuning suggestions from a deterministic ReflectionReport and — only
+ * when explicitly asked — routes them to the M23 Approval Inbox as PENDING
+ * proposals. It NEVER auto-applies anything.
+ *
+ * HARD SAFETY INVARIANTS (M26) — paramount:
+ *  - PROPOSAL-ONLY. The ONLY sink is the inbox via createProposal (status
+ *    pending). There is NO code path here that writes the global config path,
+ *    saves config, or mutates routing policy or prompts. Suggestions reason
+ *    ABOUT routing but never change it. Each proposal is kind 'note' (a no-op
+ *    record that, even when applied, mutates nothing).
+ *  - DETERMINISTIC. deriveTuning() is pure over the report — no LLM, no network.
+ *  - NO OUTWARD ACTION. Proposals sit pending; nothing is shipped or deployed.
+ *  - BOUNDED. Caps the number of suggestions emitted.
+ *  - NEVER THROWS. Degrades to [] / a no-op emit.
+ *
+ * METADATA ONLY — proposals carry titles + rationale grounded in metrics; never
+ * secret values, never raw payloads.
+ */
+import { createProposal } from '../inbox/store.js';
+// ---------------------------------------------------------------------------
+// Bounds
+// ---------------------------------------------------------------------------
+/** Max tuning suggestions derived/emitted per reflection. */
+const MAX_TUNING = 6;
+/** Minimum analyzed swarms before any quantitative heuristic fires (avoids
+ *  drawing conclusions from a 1-2 run sample). */
+const MIN_SAMPLE = 3;
+/** A localShare at/above this with zero cloud spend => the org is already
+ *  local-first; suggest raising the local-first routing threshold. */
+const HIGH_LOCAL_SHARE = 0.9;
+/** A failure cluster this size (or larger) is "recurring" => playbook-worthy. */
+const RECURRING_FAILURE_MIN = 2;
+/** A category costing at least this multiple of the fleet average looks
+ *  over-provisioned => flag as over-budget. */
+const OVER_BUDGET_MULTIPLE = 1.75;
+// ---------------------------------------------------------------------------
+// Pure derivation (exported for testing) — NO I/O, NO LLM, NO MUTATION
+// ---------------------------------------------------------------------------
+/** Round a 0..1 confidence to 2 decimals, clamped into [0,1]. */
+function clampConfidence(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    const c = Math.max(0, Math.min(1, n));
+    return Math.round(c * 100) / 100;
+}
+/**
+ * Derive PROPOSAL-ONLY tuning suggestions from a ReflectionReport. Pure over
+ * the report; never throws; never mutates anything; makes ZERO I/O or network
+ * calls. Returns at most MAX_TUNING suggestions, highest-confidence first.
+ *
+ * Heuristics (deterministic, grounded in report metrics):
+ *  - High localShare + zero cloud spend     -> "raise local-first threshold".
+ *  - A recurring failure cluster            -> "add a playbook for failure Y".
+ *  - A category succeeding ~every time      -> "lower retry cap for category X".
+ *  - A category far costlier than the fleet -> "flag over-budget category X".
+ *  - Effectiveness regressed vs prior        -> "review recent routing/policy".
+ *
+ * NOTE: every suggestion only DESCRIBES a possible change. Nothing here applies
+ * it — emitTuningProposals() routes them to the inbox as inert pending notes.
+ */
+export function deriveTuning(report) {
+    const out = [];
+    try {
+        const analyzed = report.swarmsAnalyzed | 0;
+        // -- 1. Routing: already local-first => suggest raising the threshold. ----
+        // Only when we have a real sample, the local share is dominant, and there
+        // was no cloud spend to justify keeping headroom for escalation.
+        if (analyzed >= MIN_SAMPLE &&
+            report.localShare >= HIGH_LOCAL_SHARE &&
+            report.totalCostUsd <= 0) {
+            const localPct = Math.round(report.localShare * 100);
+            out.push({
+                key: 'routing.local-first-threshold',
+                area: 'routing',
+                title: 'Raise the local-first routing threshold',
+                rationale: `${localPct}% of token usage already ran on LOCAL providers across ` +
+                    `${analyzed} swarms with $0 cloud spend. Routing could bias even more ` +
+                    `work to local models before escalating to cloud. (Suggestion only — ` +
+                    `routing is not changed.)`,
+                // More confident the larger the sample and the higher the local share.
+                confidence: clampConfidence(0.4 + report.localShare * 0.4 + (Math.min(analyzed, 20) / 20) * 0.2),
+            });
+        }
+        // -- 2. Playbook: recurring failure clusters => suggest a playbook. -------
+        for (const fm of report.topFailures ?? []) {
+            if (fm.count < RECURRING_FAILURE_MIN)
+                continue;
+            const phases = (fm.phases ?? []).filter(Boolean);
+            const where = phases.length ? ` (most often in phase ${phases[0]})` : '';
+            out.push({
+                key: `playbook.failure.${fm.key}`,
+                area: 'playbook',
+                title: `Add a playbook for recurring failure: ${fm.label}`,
+                rationale: `"${fm.label}" recurred ${fm.count} time(s)${where}. A distilled ` +
+                    `playbook capturing the fix would auto-inject into future agents and ` +
+                    `reduce repeat failures.`,
+                // Confidence scales with how often the failure recurred (caps at 1.0).
+                confidence: clampConfidence(0.45 + (Math.min(fm.count, 8) / 8) * 0.45),
+            });
+        }
+        // -- 3/4. Per-category retry + budget heuristics. ------------------------
+        const cats = report.goalCategories ?? [];
+        const fleetAvgCost = report.avgCostUsd;
+        for (const cat of cats) {
+            // 3. A category that essentially always succeeds first-try => the retry
+            //    cap for that kind of work is likely larger than needed.
+            if (cat.swarms >= MIN_SAMPLE && cat.successRate >= 1) {
+                out.push({
+                    key: `policy.retry-cap.${cat.category}`,
+                    area: 'policy',
+                    title: `Lower the retry cap for "${cat.category}" work`,
+                    rationale: `"${cat.category}" succeeded on ${cat.swarms}/${cat.swarms} swarms ` +
+                        `(100%). Retries for this category may rarely fire — a lower retry ` +
+                        `cap could cut wasted steps with little risk. (Suggestion only.)`,
+                    confidence: clampConfidence(0.35 + (Math.min(cat.swarms, 12) / 12) * 0.4),
+                });
+            }
+            // 4. A category costing far more than the fleet average => flag it.
+            if (cat.swarms >= MIN_SAMPLE &&
+                fleetAvgCost > 0 &&
+                cat.avgCostUsd >= fleetAvgCost * OVER_BUDGET_MULTIPLE) {
+                const x = cat.avgCostUsd / fleetAvgCost;
+                out.push({
+                    key: `policy.budget.${cat.category}`,
+                    area: 'policy',
+                    title: `Flag over-budget goal category: "${cat.category}"`,
+                    rationale: `"${cat.category}" averaged $${cat.avgCostUsd.toFixed(4)} per swarm ` +
+                        `— ${x.toFixed(1)}x the fleet average of ` +
+                        `$${fleetAvgCost.toFixed(4)}. Worth a budget cap or a cheaper ` +
+                        `routing tier for this category. (Suggestion only.)`,
+                    confidence: clampConfidence(0.4 + (Math.min(x - 1, 3) / 3) * 0.4),
+                });
+            }
+        }
+        // -- 5. Regression watch: effectiveness dropped week-over-week. ----------
+        const eff = report.delta?.effectivenessPct;
+        if (analyzed >= MIN_SAMPLE && typeof eff === 'number' && eff <= -10) {
+            out.push({
+                key: 'policy.effectiveness-regression',
+                area: 'policy',
+                title: 'Review recent routing/policy: effectiveness regressed',
+                rationale: `Success rate fell ${Math.abs(Math.round(eff))} points vs the prior ` +
+                    `snapshot. Recent routing or policy changes may be worth reviewing. ` +
+                    `(Suggestion only — nothing is reverted.)`,
+                confidence: clampConfidence(0.4 + (Math.min(Math.abs(eff), 50) / 50) * 0.4),
+            });
+        }
+        // Highest-confidence first, then stable by key. Bounded by MAX_TUNING.
+        out.sort((a, b) => b.confidence - a.confidence || a.key.localeCompare(b.key));
+        return out.slice(0, MAX_TUNING);
+    }
+    catch {
+        return [];
+    }
+}
+// ---------------------------------------------------------------------------
+// Public: emit to the Approval Inbox (the SOLE sink)
+// ---------------------------------------------------------------------------
+/**
+ * Convert derived TuningProposals into PENDING M23 inbox proposals via
+ * createProposal(). Returns the created Proposal records.
+ *
+ * GUARDRAIL: this is the ONLY outward sink for tuning. Each proposal is created
+ * with kind 'note' (a no-op record — applying it mutates NOTHING), origin
+ * 'manual', repo null, status 'pending'. There is NO path here that touches the
+ * global config, routing policy, or prompts. Never throws.
+ */
+export function emitTuningProposals(suggestions) {
+    const created = [];
+    try {
+        // Bounded defensively even though deriveTuning already caps the input.
+        for (const s of (suggestions ?? []).slice(0, MAX_TUNING)) {
+            try {
+                const pct = Math.round(clampConfidence(s.confidence) * 100);
+                const proposal = createProposal({
+                    repo: null,
+                    origin: 'manual',
+                    // 'note' is a no-op record: approving/applying it mutates NOTHING.
+                    kind: 'note',
+                    title: `[tuning] ${s.title}`,
+                    summary: `${s.rationale}\n\n` +
+                        `area: ${s.area} · key: ${s.key} · confidence: ${pct}%\n` +
+                        `This is a tuning SUGGESTION only — approving it records the ` +
+                        `decision but changes no configuration, routing, policy, or prompt.`,
+                });
+                created.push(proposal);
+            }
+            catch {
+                // Skip a single failed proposal; keep emitting the rest.
+            }
+        }
+        return created;
+    }
+    catch {
+        return created;
+    }
+}
+//# sourceMappingURL=tuning.js.map

package/dist/core/learn/tuning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tuning.js","sourceRoot":"","sources":["../../../src/core/learn/tuning.ts"],"names":[],"mappings":"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"}

package/dist/core/lifecycle/scaffold.d.ts

@@ -0,0 +1,43 @@
+/**
+ * M6: Project Lifecycle — Scaffolder
+ *
+ * Materializes a ProjectTemplate onto disk for `ashlr new`, then best-effort
+ * runs `git init` and registers the project in the ashlr index.
+ *
+ * SAFETY GUARDRAILS:
+ *   - REFUSES to write if the target directory already exists (no clobber).
+ *   - Writes ONLY under spec.dir; every TemplateFile path is resolved relative
+ *     to spec.dir and rejected if it escapes the directory.
+ *   - NEVER throws — all failures surface via the returned ScaffoldResult.
+ */
+import type { ScaffoldSpec, ScaffoldResult } from '../types.js';
+/** The default category bucket for new projects. */
+export declare function defaultCategory(): string;
+/**
+ * The canonical root under which all scaffolded projects must live:
+ * ~/Desktop/github. Used as the allowed-root for the in-tree write guard.
+ */
+export declare function githubRoot(): string;
+/**
+ * Resolve the canonical target directory for a project under the
+ * ~/Desktop/github/<category>/<name> tree.
+ */
+export declare function targetDir(name: string, category: string): string;
+/** Synchronous index-registration function shape (injectable for tests). */
+export type IndexRegistrar = () => {
+    registered: boolean;
+    warning?: string;
+};
+/**
+ * Scaffold a project from its template into spec.dir.
+ *
+ * Returns a ScaffoldResult; never throws. Index registration runs
+ * SYNCHRONOUSLY before returning, so `result.registered` deterministically
+ * reflects the real outcome (M6 contract).
+ *
+ * @param register Optional injected registrar (defaults to the real
+ *   createRequire-based synchronous registration). Tests inject a stub here
+ *   because vitest's `vi.mock` intercepts dynamic `import()` but NOT
+ *   `createRequire`, so the real index-engine cannot be mocked otherwise.
+ */
+export declare function scaffoldProject(spec: ScaffoldSpec, register?: IndexRegistrar): ScaffoldResult;

package/dist/core/lifecycle/scaffold.js

@@ -0,0 +1,260 @@
+/**
+ * M6: Project Lifecycle — Scaffolder
+ *
+ * Materializes a ProjectTemplate onto disk for `ashlr new`, then best-effort
+ * runs `git init` and registers the project in the ashlr index.
+ *
+ * SAFETY GUARDRAILS:
+ *   - REFUSES to write if the target directory already exists (no clobber).
+ *   - Writes ONLY under spec.dir; every TemplateFile path is resolved relative
+ *     to spec.dir and rejected if it escapes the directory.
+ *   - NEVER throws — all failures surface via the returned ScaffoldResult.
+ */
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync, chmodSync, } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep, } from 'node:path';
+import { getTemplate } from './templates.js';
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+/** The default category bucket for new projects. */
+export function defaultCategory() {
+    return 'side-projects';
+}
+/**
+ * The canonical root under which all scaffolded projects must live:
+ * ~/Desktop/github. Used as the allowed-root for the in-tree write guard.
+ */
+export function githubRoot() {
+    return resolve(join(homedir(), 'Desktop', 'github'));
+}
+/**
+ * Resolve the canonical target directory for a project under the
+ * ~/Desktop/github/<category>/<name> tree.
+ */
+export function targetDir(name, category) {
+    return resolve(join(homedir(), 'Desktop', 'github', category, name));
+}
+/**
+ * True when `child` resolves to a path strictly inside `parent`
+ * (or equal to it). Used to keep all writes under spec.dir.
+ */
+function isInside(parent, child) {
+    const rel = relative(parent, child);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+// ---------------------------------------------------------------------------
+// git
+// ---------------------------------------------------------------------------
+function gitInit(dir) {
+    try {
+        execSync('git init', { cwd: dir, stdio: 'pipe', timeout: 30_000 });
+        return { ok: true };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, warning: `git init failed: ${msg}` };
+    }
+}
+// ---------------------------------------------------------------------------
+// stack recipe detection (warning-only; provisioning is done by the CLI layer)
+// ---------------------------------------------------------------------------
+function stackInstalled() {
+    try {
+        const out = execSync('which stack 2>/dev/null', { encoding: 'utf8' }).trim();
+        return out.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// index registration (best-effort; never blocks scaffold success)
+// ---------------------------------------------------------------------------
+/**
+ * Register the new project in the ashlr index, SYNCHRONOUSLY.
+ *
+ * buildIndex / writeIndex / loadConfig are all synchronous in the real
+ * index-engine, so registration completes before scaffoldProject returns and
+ * the `registered` flag deterministically reflects the outcome (M6 contract).
+ *
+ * Modules are loaded via createRequire so this stays synchronous; failures and
+ * the (test-only) async-buildIndex case surface as a non-fatal warning with
+ * registered:false rather than blocking or throwing.
+ */
+function registerInIndex() {
+    try {
+        const require = createRequire(import.meta.url);
+        const indexMod = require('../index-engine.js');
+        let configMod = null;
+        try {
+            configMod = require('../config.js');
+        }
+        catch {
+            configMod = null;
+        }
+        const { buildIndex, writeIndex } = indexMod;
+        let cfg = undefined;
+        if (configMod && typeof configMod.loadConfig === 'function') {
+            try {
+                cfg = configMod.loadConfig();
+            }
+            catch {
+                cfg = undefined;
+            }
+        }
+        const built = buildIndex(cfg);
+        // The real buildIndex is synchronous. If a caller (or a test mock) returns a
+        // Promise, we cannot await it on this synchronous path — report it as a
+        // non-fatal skip rather than registering a half-built index.
+        if (built instanceof Promise) {
+            return {
+                registered: false,
+                warning: 'index registration skipped: buildIndex returned a Promise (async index-engine)',
+            };
+        }
+        writeIndex(built);
+        return { registered: true };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { registered: false, warning: `index registration skipped: ${msg}` };
+    }
+}
+/**
+ * Scaffold a project from its template into spec.dir.
+ *
+ * Returns a ScaffoldResult; never throws. Index registration runs
+ * SYNCHRONOUSLY before returning, so `result.registered` deterministically
+ * reflects the real outcome (M6 contract).
+ *
+ * @param register Optional injected registrar (defaults to the real
+ *   createRequire-based synchronous registration). Tests inject a stub here
+ *   because vitest's `vi.mock` intercepts dynamic `import()` but NOT
+ *   `createRequire`, so the real index-engine cannot be mocked otherwise.
+ */
+export function scaffoldProject(spec, register = registerInIndex) {
+    const result = {
+        ok: false,
+        dir: spec.dir,
+        filesWritten: [],
+        gitInitialized: false,
+        mcpWired: false,
+        registered: false,
+        warnings: [],
+    };
+    try {
+        // SAFETY (defense-in-depth): the write-performing layer self-defends. Refuse
+        // any spec.dir that is not the cwd-relative `--here` form AND not strictly
+        // inside ~/Desktop/github/. This stops out-of-tree creation even if a CLI
+        // caller forgets to validate (e.g. a crafted --category). spec.allowAnyRoot
+        // is the explicit opt-out used by hermetic tmp-dir tests.
+        if (!spec.allowAnyRoot) {
+            const root = githubRoot();
+            const inTree = spec.dir === root || spec.dir.startsWith(root + sep);
+            const here = isInside(resolve(process.cwd()), spec.dir);
+            if (!inTree && !here) {
+                result.error =
+                    `Refusing to scaffold outside the github tree: ${spec.dir} ` +
+                        `(allowed root: ${root}).`;
+                return result;
+            }
+        }
+        // SAFETY: refuse to overwrite an existing directory.
+        if (existsSync(spec.dir)) {
+            result.error = `Target directory already exists: ${spec.dir}. Refusing to overwrite.`;
+            return result;
+        }
+        // Resolve the template.
+        const template = getTemplate(spec.templateId);
+        if (!template) {
+            result.error = `Unknown template: "${spec.templateId}".`;
+            return result;
+        }
+        // Build the file list.
+        let files;
+        try {
+            files = template.files({ name: spec.name, category: spec.category });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            result.error = `Template "${spec.templateId}" failed to produce files: ${msg}`;
+            return result;
+        }
+        // Create the root directory.
+        mkdirSync(spec.dir, { recursive: true });
+        // Write each file, guarding against path escape.
+        let mcpWired = false;
+        for (const file of files) {
+            const targetPath = resolve(spec.dir, file.path);
+            if (!isInside(spec.dir, targetPath)) {
+                result.warnings.push(`skipped file outside project dir: ${file.path}`);
+                continue;
+            }
+            mkdirSync(dirname(targetPath), { recursive: true });
+            writeFileSync(targetPath, file.content);
+            if (typeof file.mode === 'number') {
+                try {
+                    chmodSync(targetPath, file.mode);
+                }
+                catch {
+                    // mode is best-effort; ignore on platforms that reject it
+                }
+            }
+            result.filesWritten.push(targetPath);
+            // Detect the .mcp.json wiring the ashlr gateway.
+            if (targetPath === resolve(spec.dir, '.mcp.json')) {
+                try {
+                    const parsed = JSON.parse(file.content);
+                    if (parsed.mcpServers && 'ashlr' in parsed.mcpServers) {
+                        mcpWired = true;
+                    }
+                }
+                catch {
+                    // not valid JSON — leave mcpWired false
+                }
+            }
+        }
+        result.mcpWired = mcpWired;
+        // stack recipe: warn (only) when requested but stack is not installed.
+        if (spec.stackRecipe) {
+            if (!stackInstalled()) {
+                result.warnings.push(`stack recipe "${spec.stackRecipe}" requested but \`stack\` is not installed — skipping provisioning.`);
+            }
+        }
+        // git init (best-effort).
+        if (spec.git) {
+            const git = gitInit(spec.dir);
+            result.gitInitialized = git.ok;
+            if (git.warning) {
+                result.warnings.push(git.warning);
+            }
+        }
+        // Index registration (synchronous — buildIndex/writeIndex are sync). Doing
+        // this inline makes `result.registered` deterministically reflect the real
+        // outcome before we return, satisfying the M6 contract. Never throws.
+        let reg;
+        try {
+            reg = register();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            reg = { registered: false, warning: `index registration skipped: ${msg}` };
+        }
+        if (reg.warning) {
+            result.warnings.push(reg.warning);
+        }
+        result.registered = reg.registered;
+        result.ok = true;
+        return result;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        result.error = `Scaffold failed: ${msg}`;
+        result.ok = false;
+        return result;
+    }
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/core/lifecycle/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../../src/core/lifecycle/scaffold.ts"],"names":[],"mappings":"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"}

package/dist/core/lifecycle/ship.d.ts

@@ -0,0 +1,48 @@
+/**
+ * core/lifecycle/ship.ts — pre-ship gate + optional deploy for `ashlr ship`.
+ *
+ * `runShipGate` is READ-ONLY: it scans, runs scripts, and reports.
+ * `deploy` is the ONLY place an outward action can happen, and ONLY when
+ * opts.confirm === true. Default is always dry-run.
+ *
+ * Both functions NEVER throw — errors are captured in ShipCheck / detail strings.
+ */
+import type { ShipGate } from '../types.js';
+/**
+ * Run all pre-ship gate checks for the project at `projectPath`.
+ *
+ * READ-ONLY: scans files and runs npm scripts. Never deploys or pushes.
+ * Never throws — all errors are captured as ShipCheck fail/warn/skip entries.
+ *
+ * Checks run in order:
+ *   1. supply-chain  — binshield (if installed) else built-in dep sanity check
+ *   2. test          — npm run test (if script exists)
+ *   3. lint          — npm run lint (if script exists)
+ *   4. build         — npm run build (if script exists)
+ *   5. secrets       — git-tracked .env files + obvious key patterns
+ *
+ * `passed` is true when no check has status 'fail'.
+ */
+export declare function runShipGate(projectPath: string, opts: {
+    strict: boolean;
+}): Promise<ShipGate>;
+/**
+ * Optionally deploy the project to the named target.
+ *
+ * DRY-RUN BY DEFAULT: only runs the real deploy command when `opts.confirm`
+ * is true. This is the ONLY function in the codebase that may execute an
+ * outward action.
+ *
+ * Supported targets: vercel | stack | morphkit | gh
+ * Detect every tool at runtime via `which`. If the tool is not installed,
+ * return a guidance string instead of failing.
+ *
+ * Never throws.
+ */
+export declare function deploy(projectPath: string, target: string, opts: {
+    confirm: boolean;
+}): Promise<{
+    ran: boolean;
+    dryRun: boolean;
+    detail: string;
+}>;