baselane 0.1.0

package/dist/cli.js

@@ -0,0 +1,231 @@
+import { readFile } from "node:fs/promises";
+import { auditRepo, formatAuditReport } from "./audit.js";
+import { applyResolvedPack } from "./apply.js";
+import { distributePack, GithubClient } from "@baselane/distribute";
+import { reportAdoption } from "./report.js";
+import { loadBuiltinPack, validatePack } from "@baselane/packs";
+import { formatGraphSummary, runGraph } from "./graph.js";
+import { formatMapSummary, runMap } from "./map.js";
+import { runDraftPack, formatDraftSummary } from "./draft-pack.js";
+import { runInstall, formatInstallReport } from "./install.js";
+import { runUpdate } from "./update.js";
+import { runDrift, formatDriftReport } from "./drift-cmd.js";
+import { runPublish } from "./publish.js";
+import { LocalDirFileSource, analyze, analyzeConventions, analyzeDesignTokens, narrateArchitecture, narrateDesign, pickSamples, pickDesignSamples, } from "@baselane/analyze";
+// Exported so docs-site/src/pages/cli.ts can embed it verbatim at build time — the CLI reference
+// page can never drift into a syntax this CLI doesn't actually accept.
+export const USAGE = [
+    "usage:",
+    "  baselane audit <dir> [--json]",
+    "  baselane apply <dir> (--pack <id> | --pack-file <path>) [--force] [--dry-run]",
+    "  baselane distribute <owner/repo> (--pack <id> | --pack-file <path>) [--portal <url>]",
+    "  baselane draft-pack <dir> [--json]",
+    "  baselane graph <dir> [--json]",
+    "  baselane map <dir> [--json] [--llm] [--dry-run]",
+    "  baselane install [github:owner/repo@ref | @scope/name[@version] | owner/repo@skill] [-g] [--dir <d>] [--dry-run] [--json]",
+    "  baselane update [github:owner/repo | @scope/name] [-g] [--dir <d>] [--dry-run]",
+    "  baselane drift [-g] [--dir <d>] [--json]",
+    "  baselane publish @scope/name --source github:owner/repo --ref <tag> [--registry URL] [--json]",
+].join("\n");
+function argValue(argv, flag) {
+    const i = argv.indexOf(flag);
+    return i !== -1 ? argv[i + 1] : undefined;
+}
+// #6: --pack-file is the escape hatch for a custom pack the CLI doesn't ship (a portal-authored
+// or AI-drafted one saved to disk) — loadBuiltinPack only ever knows built-in ids. Same rule as
+// every other pack entry point in this repo: validatePack is the sole authority, so a hand-edited
+// file gets exactly the same validation a built-in pack.json does before it's ever rendered.
+async function loadPackFile(path) {
+    const raw = await readFile(path, "utf8");
+    return validatePack(JSON.parse(raw));
+}
+/** Resolves --pack/--pack-file into a WorkflowPack, requiring exactly one of the two. */
+async function resolvePackArg(packId, packFile) {
+    return packFile ? loadPackFile(packFile) : loadBuiltinPack(packId);
+}
+export async function main(argv, deps = {}) {
+    const [cmd, dir] = argv;
+    // #29: an explicit help request is not an error — print usage to stdout and exit 0. A genuinely
+    // unknown or missing command still falls through to the stderr + exit-1 path below.
+    if (cmd === "--help" || cmd === "-h" || cmd === "help") {
+        console.log(USAGE);
+        return 0;
+    }
+    try {
+        if (cmd === "audit" && dir) {
+            const result = await auditRepo(dir);
+            console.log(argv.includes("--json") ? JSON.stringify(result, null, 2) : formatAuditReport(result));
+            return 0;
+        }
+        if (cmd === "apply" && dir) {
+            const packId = argValue(argv, "--pack");
+            const packFile = argValue(argv, "--pack-file");
+            if ((!packId && !packFile) || (packId && packFile)) {
+                console.error(USAGE);
+                return 1;
+            }
+            const pack = await resolvePackArg(packId, packFile);
+            const r = await applyResolvedPack(dir, pack, {
+                force: argv.includes("--force"),
+                dryRun: argv.includes("--dry-run"),
+            });
+            const label = argv.includes("--dry-run") ? "would write" : "wrote";
+            console.log(`baselane apply ${pack.id}: ${label} ${r.written.length} file(s)` +
+                (r.skipped.length ? `, skipped ${r.skipped.length} existing (use --force): ${r.skipped.join(", ")}` : ""));
+            return 0;
+        }
+        if (cmd === "graph" && dir) {
+            const r = await runGraph(dir);
+            console.log(argv.includes("--json") ? JSON.stringify(r.graph, null, 2) : formatGraphSummary(r.graph, r.written));
+            return 0;
+        }
+        if (cmd === "map" && dir) {
+            let narration = null;
+            let designNarration = null;
+            if (argv.includes("--llm")) {
+                const apiKey = process.env.BASELANE_ANTHROPIC_KEY ?? process.env.ANTHROPIC_API_KEY;
+                if (!apiKey) {
+                    console.error("baselane map error: --llm needs BASELANE_ANTHROPIC_KEY or ANTHROPIC_API_KEY. " +
+                        "Run without --llm for the deterministic map.");
+                    return 1;
+                }
+                const source = new LocalDirFileSource(dir);
+                const [profile, conventions, samples, tokens, designSamples] = await Promise.all([
+                    analyze(source),
+                    analyzeConventions(source),
+                    pickSamples(source),
+                    analyzeDesignTokens(source),
+                    pickDesignSamples(source),
+                ]);
+                try {
+                    narration = await narrateArchitecture({ profile, conventions, samples }, { apiKey, fetchImpl: deps.fetchImpl });
+                    if (tokens.hasUiSurface) {
+                        designNarration = await narrateDesign({ tokens, samples: designSamples }, { apiKey, fetchImpl: deps.fetchImpl });
+                    }
+                }
+                catch (err) {
+                    console.error(`baselane map error: ${err instanceof Error ? err.message : String(err)}`);
+                    return 1;
+                }
+            }
+            const r = await runMap(dir, { dryRun: argv.includes("--dry-run"), narration, designNarration });
+            console.log(argv.includes("--json")
+                ? JSON.stringify({ profile: r.profile, conventions: r.conventions, tokens: r.tokens }, null, 2)
+                : argv.includes("--dry-run")
+                    ? [r.architectureMd, r.designMd].filter((s) => s !== null).join("\n")
+                    : formatMapSummary(r));
+            return 0;
+        }
+        if (cmd === "draft-pack" && dir) {
+            const result = await runDraftPack(dir);
+            console.log(argv.includes("--json") ? JSON.stringify(result.pack, null, 2) : formatDraftSummary(result));
+            return 0;
+        }
+        if (cmd === "distribute" && dir) {
+            const packId = argValue(argv, "--pack");
+            const packFile = argValue(argv, "--pack-file");
+            if ((!packId && !packFile) || (packId && packFile)) {
+                console.error(USAGE);
+                return 1;
+            }
+            const token = process.env.GITHUB_TOKEN;
+            if (!token) {
+                console.error("baselane error: GITHUB_TOKEN is required for distribute");
+                return 1;
+            }
+            const portalUrl = argValue(argv, "--portal");
+            const portalToken = process.env.BASELANE_PORTAL_TOKEN;
+            if (portalUrl && !portalToken) {
+                console.error("baselane error: BASELANE_PORTAL_TOKEN is required with --portal");
+                return 1;
+            }
+            const pack = await resolvePackArg(packId, packFile);
+            const r = await distributePack(new GithubClient({ token }), dir, pack);
+            console.log(`baselane distribute ${pack.id}: opened ${r.prUrl} (${r.fileCount} file(s) on ${r.branch})`);
+            if (portalUrl && portalToken) {
+                try {
+                    await reportAdoption(portalUrl, portalToken, {
+                        repo: dir,
+                        packId: pack.id,
+                        version: pack.version,
+                        prUrl: r.prUrl,
+                    });
+                    console.log(`baselane distribute: adoption recorded at ${portalUrl}`);
+                }
+                catch (reportErr) {
+                    console.error(`baselane warning: PR opened but adoption report failed: ${reportErr instanceof Error ? reportErr.message : String(reportErr)}`);
+                }
+            }
+            return 0;
+        }
+        if (cmd === "install") {
+            const source = argv[1] && !argv[1].startsWith("-") ? argv[1] : undefined;
+            const json = argv.includes("--json");
+            const report = await runInstall({
+                source,
+                global: argv.includes("-g") || argv.includes("--global"),
+                dir: argValue(argv, "--dir"),
+                dryRun: argv.includes("--dry-run"),
+                json,
+                token: process.env.GITHUB_TOKEN,
+                registryBase: process.env.BASELANE_REGISTRY,
+                fetchImpl: deps.fetchImpl,
+                // --json means stdout must be pure JSON — route notices to stderr instead of the default console.log
+                log: json ? (l) => console.error(l) : undefined,
+            });
+            console.log(json ? JSON.stringify(report, null, 2) : formatInstallReport(report));
+            return 0;
+        }
+        if (cmd === "update") {
+            const name = argv[1] && !argv[1].startsWith("-") ? argv[1] : undefined;
+            const json = argv.includes("--json");
+            await runUpdate({
+                name,
+                global: argv.includes("-g") || argv.includes("--global"),
+                dir: argValue(argv, "--dir"),
+                dryRun: argv.includes("--dry-run"),
+                token: process.env.GITHUB_TOKEN,
+                registryBase: process.env.BASELANE_REGISTRY,
+                fetchImpl: deps.fetchImpl,
+                log: json ? (l) => console.error(l) : undefined,
+            });
+            return 0;
+        }
+        if (cmd === "drift") {
+            const report = await runDrift({
+                global: argv.includes("-g") || argv.includes("--global"),
+                dir: argValue(argv, "--dir"),
+            });
+            console.log(argv.includes("--json") ? JSON.stringify(report, null, 2) : formatDriftReport(report));
+            return report.clean ? 0 : 1;
+        }
+        if (cmd === "publish") {
+            const name = argv[1] && !argv[1].startsWith("-") ? argv[1] : undefined;
+            const source = argValue(argv, "--source");
+            const ref = argValue(argv, "--ref");
+            if (!name || !source || !ref) {
+                console.error(USAGE);
+                return 1;
+            }
+            const json = argv.includes("--json");
+            const result = await runPublish({
+                name,
+                sourceName: source,
+                ref,
+                registry: argValue(argv, "--registry") ?? process.env.BASELANE_REGISTRY,
+                token: process.env.GITHUB_TOKEN,
+                fetchImpl: deps.fetchImpl,
+                // --json means stdout must be pure JSON — route notices to stderr, same idiom as install/update
+                log: json ? (l) => console.error(l) : undefined,
+            });
+            console.log(json ? JSON.stringify(result, null, 2) : result.message);
+            return result.ok ? 0 : 1;
+        }
+        console.error(USAGE);
+        return 1;
+    }
+    catch (err) {
+        console.error(`baselane error: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}

package/dist/draft-pack.d.ts

@@ -0,0 +1,3 @@
+import { type DraftPackResult } from "@baselane/packs";
+export declare function runDraftPack(dir: string): Promise<DraftPackResult>;
+export declare function formatDraftSummary(result: DraftPackResult): string;

package/dist/draft-pack.js

@@ -0,0 +1,22 @@
+import { basename, resolve } from "node:path";
+import { LocalDirFileSource, analyze, analyzeConventions } from "@baselane/analyze";
+import { composeDraftPack } from "@baselane/packs";
+export async function runDraftPack(dir) {
+    const source = new LocalDirFileSource(dir);
+    const [profile, conventions] = await Promise.all([analyze(source), analyzeConventions(source)]);
+    return composeDraftPack({ profile, conventions, repoName: basename(resolve(dir)) });
+}
+export function formatDraftSummary(result) {
+    const { pack } = result;
+    const caps = (pack.capabilities ?? []).map((c) => c.type).join(", ") || "none";
+    return [
+        "baselane draft-pack",
+        "",
+        `Pack: ${pack.id} — ${pack.title}`,
+        `Commands: ${pack.commands.map((c) => c.name).join(", ") || "none"}`,
+        `Capabilities: ${caps}`,
+        "",
+        "Paste this JSON into the pack builder (or save it) — it is an editable draft, not published:",
+        JSON.stringify(pack, null, 2),
+    ].join("\n");
+}

package/dist/drift-cmd.d.ts

@@ -0,0 +1,28 @@
+export type PathDriftStatus = "ok" | "modified" | "missing" | "no-hash-recorded";
+export type RegionDriftStatus = "ok" | "region-missing" | "version-drift" | "content-drift" | "file-missing";
+export interface DriftReport {
+    manifestPath: string;
+    vendored: Array<{
+        path: string;
+        status: PathDriftStatus;
+    }>;
+    regions: Array<{
+        path: string;
+        packId: string;
+        pinnedVersion: string;
+        status: RegionDriftStatus;
+    }>;
+    capabilities: Array<{
+        capability: string;
+        path: string;
+        status: PathDriftStatus;
+    }>;
+    unreadable: string[];
+    clean: boolean;
+}
+export declare function runDrift(opts: {
+    global: boolean;
+    dir?: string;
+    homeDir?: string;
+}): Promise<DriftReport>;
+export declare function formatDriftReport(r: DriftReport): string;

package/dist/drift-cmd.js

@@ -0,0 +1,98 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { extractManagedRegions, sha256Hex } from "@baselane/packs";
+import { readManifestWithFallback, targetLocation } from "@baselane/materialize";
+/** null = absent (ENOENT/ENOTDIR); "unreadable" recorded by the caller on any other error. */
+async function readOrClassify(abs, rel, unreadable) {
+    try {
+        return await readFile(abs, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return null;
+        unreadable.push(rel);
+        return null;
+    }
+}
+export async function runDrift(opts) {
+    const loc = targetLocation({ global: opts.global, dir: opts.dir, homeDir: opts.homeDir });
+    const { manifest } = await readManifestWithFallback(loc);
+    if (manifest === null)
+        throw new Error(`drift: no harness.json at ${loc.manifestPath} — run baselane install first`);
+    const unreadable = [];
+    const vendored = [];
+    for (const entry of manifest.materialized.vendored) {
+        const before = unreadable.length;
+        const current = await readOrClassify(join(loc.targetDir, entry.path), entry.path, unreadable);
+        if (unreadable.length > before)
+            continue; // reported, not statused
+        const status = current === null ? "missing"
+            : entry.sha256 === null ? "no-hash-recorded"
+                : sha256Hex(current) === entry.sha256 ? "ok"
+                    : "modified";
+        vendored.push({ path: entry.path, status });
+    }
+    const regions = [];
+    for (const entry of manifest.materialized.managedRegions) {
+        const before = unreadable.length;
+        const current = await readOrClassify(join(loc.targetDir, entry.path), entry.path, unreadable);
+        if (unreadable.length > before)
+            continue;
+        const found = current === null ? [] : extractManagedRegions(current);
+        for (const receipt of entry.regions) {
+            const region = found.find((r) => r.packId === receipt.packId);
+            const status = current === null ? "file-missing"
+                : !region ? "region-missing"
+                    : region.version !== receipt.version ? "version-drift"
+                        : sha256Hex(region.body) !== receipt.sha256 ? "content-drift"
+                            : "ok";
+            regions.push({ path: entry.path, packId: receipt.packId, pinnedVersion: receipt.version, status });
+        }
+    }
+    // Capability receipts (M4: committed-vs-cache split) — same hash-compare as vendored, reported
+    // under the capability's name. sha256 is always recorded on a receipt path (unlike legacy
+    // vendored entries), so no "no-hash-recorded" case here. Legacy manifests normalize
+    // materialized.capabilities to {} (validateManifest), so this loop is a no-op for them.
+    const capabilities = [];
+    for (const [capability, receipt] of Object.entries(manifest.materialized.capabilities)) {
+        for (const entry of receipt.paths) {
+            const before = unreadable.length;
+            const current = await readOrClassify(join(loc.targetDir, entry.path), entry.path, unreadable);
+            if (unreadable.length > before)
+                continue;
+            const status = current === null ? "missing" : sha256Hex(current) === entry.sha256 ? "ok" : "modified";
+            capabilities.push({ capability, path: entry.path, status });
+        }
+    }
+    const clean = unreadable.length === 0 &&
+        vendored.every((v) => v.status === "ok") &&
+        regions.every((r) => r.status === "ok") &&
+        capabilities.every((c) => c.status === "ok");
+    return { manifestPath: loc.manifestPath, vendored, regions, capabilities, unreadable, clean };
+}
+export function formatDriftReport(r) {
+    if (r.clean)
+        return `baselane drift: clean (${r.vendored.length} vendored file(s), ${r.regions.length} region(s) verified)`;
+    const lines = [`baselane drift: DRIFT DETECTED (${r.manifestPath})`];
+    for (const v of r.vendored) {
+        if (v.status === "ok")
+            continue;
+        lines.push(v.status === "no-hash-recorded"
+            ? `  ~ ${v.path}: no hash recorded (pre-M2 install) — reinstall to record hashes`
+            : `  ! ${v.path}: ${v.status}`);
+    }
+    for (const g of r.regions) {
+        if (g.status === "ok")
+            continue;
+        lines.push(`  ! ${g.path} [${g.packId}@${g.pinnedVersion}]: ${g.status}`);
+    }
+    for (const c of r.capabilities) {
+        if (c.status === "ok")
+            continue;
+        lines.push(`  ! ${c.path} [capability:${c.capability}]: ${c.status}`);
+    }
+    for (const u of r.unreadable)
+        lines.push(`  ? ${u}: unreadable — skipped (fix permissions and re-run)`);
+    return lines.join("\n");
+}

package/dist/graph.d.ts

@@ -0,0 +1,10 @@
+import { type ImportGraph } from "@baselane/analyze";
+export interface GraphResult {
+    graph: ImportGraph;
+    /** Repo-relative paths written, in write order. */
+    written: string[];
+}
+/** Scans `dir` and writes `.baselane/graph.json` + `.baselane/graph/GRAPH.md` through the containment guard. */
+export declare function runGraph(dir: string): Promise<GraphResult>;
+/** One-screen human summary: totals + top fan-in + what was written. */
+export declare function formatGraphSummary(graph: ImportGraph, written: string[]): string;

package/dist/graph.js

@@ -0,0 +1,44 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { LocalDirFileSource, buildImportGraph, renderGraphMd } from "@baselane/analyze";
+import { assertInsideDir } from "./apply.js";
+/** Scans `dir` and writes `.baselane/graph.json` + `.baselane/graph/GRAPH.md` through the containment guard. */
+export async function runGraph(dir) {
+    const graph = await buildImportGraph(new LocalDirFileSource(dir));
+    const outputs = [
+        [".baselane/graph.json", JSON.stringify(graph, null, 2) + "\n"],
+        [".baselane/graph/GRAPH.md", renderGraphMd(graph)],
+    ];
+    const written = [];
+    for (const [rel, content] of outputs) {
+        const abs = assertInsideDir(dir, rel);
+        await mkdir(dirname(abs), { recursive: true });
+        await writeFile(abs, content, "utf8");
+        written.push(rel);
+    }
+    return { graph, written };
+}
+function topFanIn(graph, limit) {
+    const fanIn = new Map();
+    for (const e of graph.edges)
+        fanIn.set(e.to, (fanIn.get(e.to) ?? 0) + 1);
+    return [...fanIn.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, limit);
+}
+/** One-screen human summary: totals + top fan-in + what was written. */
+export function formatGraphSummary(graph, written) {
+    const modules = graph.nodes.filter((n) => n.kind === "module").length;
+    const externals = graph.nodes.filter((n) => n.kind === "external").length;
+    const top = topFanIn(graph, 5);
+    return [
+        "baselane graph",
+        "",
+        `Modules: ${modules}`,
+        `External packages: ${externals}`,
+        `Edges: ${graph.edges.length}`,
+        "",
+        "Top fan-in (most depended-on):",
+        ...(top.length > 0 ? top.map(([id, count], i) => `  ${i + 1}. ${id} (${count})`) : ["  (none)"]),
+        "",
+        `Wrote: ${written.join(", ")}`,
+    ].join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { auditRepo, formatAuditReport, type AuditResult } from "./audit.ts";
+export { applyPack, type ApplyOptions, type ApplyResult } from "./apply.ts";
+export { buildDistribution, distributePack, type Distribution, GithubApiError, GithubClient } from "@baselane/distribute";
+export { main } from "./cli.ts";
+export { reportAdoption, type AdoptionReport } from "./report.ts";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { auditRepo, formatAuditReport } from "./audit.js";
+export { applyPack } from "./apply.js";
+export { buildDistribution, distributePack, GithubApiError, GithubClient } from "@baselane/distribute";
+export { main } from "./cli.js";
+export { reportAdoption } from "./report.js";

package/dist/install.d.ts

@@ -0,0 +1,4 @@
+export { runInstall, installFromManifest } from "@baselane/materialize";
+export type { InstallOptions, InstallReport } from "@baselane/materialize";
+import { type InstallReport } from "@baselane/materialize";
+export declare function formatInstallReport(r: InstallReport): string;

package/dist/install.js

@@ -0,0 +1,12 @@
+export { runInstall, installFromManifest } from "@baselane/materialize";
+import { decodeSkillPin } from "@baselane/materialize";
+export function formatInstallReport(r) {
+    const head = `${r.dryRun ? "DRY RUN — " : ""}baselane install → ${r.targetDir}`;
+    const packs = Object.entries(r.packs).map(([n, p]) => {
+        const { ref, onlySkill } = decodeSkillPin(p);
+        return `  ${n}@${ref}${onlySkill ? ` (skill: ${onlySkill})` : ""}`;
+    });
+    const body = `${r.dryRun ? "would write" : "wrote"} ${r.writes.length} file(s), removed ${r.deletes.length}, ` +
+        `backed up ${r.driftedBackedUp.length} drifted (*.baselane-bak), left ${r.unchanged.length} unchanged`;
+    return [head, ...packs, body, ...r.notes.map((n) => `  note: ${n}`)].join("\n");
+}

package/dist/map.d.ts

@@ -0,0 +1,15 @@
+import { type AnalysisProfile, type ConventionsReport, type DesignNarration, type DesignTokensReport, type NarrationSections } from "@baselane/analyze";
+export interface MapResult {
+    profile: AnalysisProfile;
+    conventions: ConventionsReport;
+    tokens: DesignTokensReport;
+    architectureMd: string;
+    designMd: string | null;
+    written: string[];
+}
+export declare function runMap(dir: string, opts?: {
+    dryRun?: boolean;
+    narration?: NarrationSections | null;
+    designNarration?: DesignNarration | null;
+}): Promise<MapResult>;
+export declare function formatMapSummary(result: MapResult): string;

package/dist/map.js

@@ -0,0 +1,63 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { LocalDirFileSource, analyze, analyzeConventions, analyzeDesignTokens, buildImportGraph, renderArchitectureMd, renderDesignMd, DESIGN_REGION_ID, DESIGN_REGION_VERSION, SYSTEM_MAP_REGION_ID, SYSTEM_MAP_REGION_VERSION, } from "@baselane/analyze";
+import { mergeManagedRegion } from "@baselane/packs";
+import { assertInsideDir } from "./apply.js";
+export async function runMap(dir, opts = {}) {
+    const source = new LocalDirFileSource(dir);
+    const [profile, graph, conventions, tokens] = await Promise.all([
+        analyze(source),
+        buildImportGraph(source),
+        analyzeConventions(source),
+        analyzeDesignTokens(source),
+    ]);
+    const archBody = renderArchitectureMd({ profile, graph, conventions, narration: opts.narration ?? null });
+    const architectureMd = mergeManagedRegion(await readIfExists(join(dir, "ARCHITECTURE.md")), archBody, SYSTEM_MAP_REGION_ID, SYSTEM_MAP_REGION_VERSION);
+    let designMd = null;
+    if (tokens.hasUiSurface) {
+        const designBody = renderDesignMd({ tokens, narration: opts.designNarration ?? null });
+        designMd = mergeManagedRegion(await readIfExists(join(dir, "DESIGN.md")), designBody, DESIGN_REGION_ID, DESIGN_REGION_VERSION);
+    }
+    const written = [];
+    if (!opts.dryRun) {
+        const outputs = [
+            ["ARCHITECTURE.md", architectureMd],
+            [".baselane/system-map/report.json", JSON.stringify({ profile, conventions, tokens }, null, 2) + "\n"],
+        ];
+        if (designMd !== null)
+            outputs.push(["DESIGN.md", designMd]);
+        for (const [rel, content] of outputs) {
+            const abs = assertInsideDir(dir, rel);
+            await mkdir(dirname(abs), { recursive: true });
+            await writeFile(abs, content, "utf8");
+            written.push(rel);
+        }
+    }
+    return { profile, conventions, tokens, architectureMd, designMd, written };
+}
+/** Reads a file, returning null (not throwing) when it does not exist. */
+async function readIfExists(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        return null;
+    }
+}
+export function formatMapSummary(result) {
+    const hidden = result.conventions.rules.filter((r) => !r.enforced).length;
+    const design = result.tokens.hasUiSurface
+        ? `Design tokens: ${result.tokens.colors.length} colors, ${result.tokens.fonts.length} fonts, ${result.tokens.radii.length} radii${result.written.includes("DESIGN.md") ? " — DESIGN.md written" : ""}`
+        : "Design: no UI surface detected — DESIGN.md skipped";
+    return [
+        "baselane map",
+        "",
+        `Languages: ${result.profile.languages.join(", ") || "(none)"}`,
+        `Conventions measured over ${result.conventions.sampledFiles} files — rules: ${result.conventions.rules.length} (${hidden} hidden), mixed: ${result.conventions.mixed.length}`,
+        design,
+        "",
+        result.written.length > 0 ? `Wrote: ${result.written.join(", ")}` : "(dry-run — nothing written)",
+    ].join("\n");
+}

package/dist/publish.d.ts

@@ -0,0 +1,27 @@
+export interface PublishOptions {
+    /** `@scope/name` to publish under. */
+    name: string;
+    /** `github:owner/repo` source, per `isGitSourceName`. */
+    sourceName: string;
+    /** Version tag to resolve and publish from, e.g. "v1.2.0". */
+    ref: string;
+    registry?: string;
+    token?: string;
+    fetchImpl?: typeof fetch;
+    log?: (line: string) => void;
+}
+export interface PublishResult {
+    ok: boolean;
+    status: number;
+    name: string;
+    version: string;
+    sha: string;
+    message: string;
+}
+/** `baselane publish`: resolves `ref` → sha via `resolveGitSource`, validates the pack builds via
+ * `packFromFileset`, then POSTs to the registry's publish endpoint with the GitHub token as
+ * bearer auth. The token is read by the caller (cli.ts) from `GITHUB_TOKEN` and passed in here —
+ * this function never reads env itself (same seam as runInstall/runUpdate) — but it OWNS the
+ * "token required" check, since unlike install/update (which can proceed unauthenticated, just
+ * rate-limited), publish is inherently an authenticated action with no valid unauthenticated path. */
+export declare function runPublish(opts: PublishOptions): Promise<PublishResult>;

package/dist/publish.js

@@ -0,0 +1,76 @@
+import { parseGitSourceName, resolveGitSource } from "@baselane/distribute";
+import { packFromFileset } from "@baselane/packs";
+import { DEFAULT_REGISTRY } from "@baselane/materialize";
+// Mirrors packages/packs/src/pack-from-fileset.ts's stampVersion tag grammar — kept in sync
+// deliberately rather than exported/shared, since the two call sites need it for different
+// reasons (stampVersion falls back to `0.0.0+sha` for a non-tag ref; publish instead REJECTS a
+// non-tag ref outright, because the registry only accepts strict `X.Y.Z` semver — see
+// apps/portal/src/registry-index.ts's VERSION_RE — and a `0.0.0+sha` publish would just bounce
+// off the server as a 400 after already doing the network work).
+const VERSION_TAG_RE = /^v?(\d+\.\d+\.\d+)$/;
+/** `baselane publish`: resolves `ref` → sha via `resolveGitSource`, validates the pack builds via
+ * `packFromFileset`, then POSTs to the registry's publish endpoint with the GitHub token as
+ * bearer auth. The token is read by the caller (cli.ts) from `GITHUB_TOKEN` and passed in here —
+ * this function never reads env itself (same seam as runInstall/runUpdate) — but it OWNS the
+ * "token required" check, since unlike install/update (which can proceed unauthenticated, just
+ * rate-limited), publish is inherently an authenticated action with no valid unauthenticated path. */
+export async function runPublish(opts) {
+    if (!opts.token) {
+        throw new Error("publish: GITHUB_TOKEN is required to publish");
+    }
+    const tagMatch = VERSION_TAG_RE.exec(opts.ref);
+    if (!tagMatch) {
+        throw new Error(`publish: "${opts.ref}" is not a semver version tag — registry versions are semver ` +
+            `(e.g. "v1.2.0"); publish from a version tag, not a branch, sha, or arbitrary ref`);
+    }
+    const version = tagMatch[1];
+    const registryBase = opts.registry ?? DEFAULT_REGISTRY;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const token = opts.token;
+    const { repo } = parseGitSourceName(opts.sourceName);
+    const resolved = await resolveGitSource({
+        name: opts.sourceName, ref: opts.ref, token, fetchImpl, onNotice: opts.log,
+    });
+    const { pack } = await packFromFileset(resolved.files, { repoName: repo, ref: opts.ref, sha: resolved.sha });
+    const res = await fetchImpl(`${registryBase}/registry/v1/publish`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+        body: JSON.stringify({
+            name: opts.name,
+            version,
+            source: { name: opts.sourceName, ref: opts.ref, sha: resolved.sha },
+            packId: pack.id,
+            description: pack.summary.slice(0, 300),
+        }),
+    });
+    const shaShort = resolved.sha.slice(0, 7);
+    const base = { name: opts.name, version, sha: resolved.sha };
+    switch (res.status) {
+        case 201:
+            return { ...base, ok: true, status: 201, message: `published ${opts.name}@${version} (sha ${shaShort})` };
+        case 409:
+            return { ...base, ok: false, status: 409, message: `publish: ${opts.name}@${version} — version already published — bump the tag` };
+        case 403:
+            return {
+                ...base, ok: false, status: 403,
+                message: `publish: "${opts.name}" does not match your authenticated GitHub user or org`,
+            };
+        case 401:
+            return { ...base, ok: false, status: 401, message: "publish: GITHUB_TOKEN was rejected — check it is valid and not expired" };
+        case 400: {
+            const detail = await readErrorDetail(res);
+            return { ...base, ok: false, status: 400, message: `publish: request rejected${detail ? ` (${detail})` : ""} — check the source/sha` };
+        }
+        default:
+            throw new Error(`publish: unexpected response HTTP ${res.status} from ${registryBase}`);
+    }
+}
+async function readErrorDetail(res) {
+    try {
+        const body = (await res.json());
+        return typeof body.error === "string" ? body.error : "";
+    }
+    catch {
+        return "";
+    }
+}