pinnace 0.0.0 → 0.1.0

package/dist/car/car-build.d.ts

@@ -0,0 +1,26 @@
+/** The result of building a CAR: its raw bytes and its authoritative root CID. */
+export interface BuiltCar {
+    /** The complete CAR file bytes (header carries {@link BuiltCar.rootCid}). */
+    readonly carBytes: Uint8Array;
+    /** The site's UnixFS directory root CID, as the LAST encoder block. */
+    readonly rootCid: string;
+}
+/**
+ * Build a CAR for a site source directory, entirely in-process.
+ *
+ * @param sourceDir the site's built output directory (its CONTENTS become the
+ *   CAR root — the directory itself is NOT wrapped in an extra segment).
+ * @returns the CAR bytes plus the authoritative root CID (the last block the
+ *   directory encoder emits, mirrored into the CAR header).
+ * @throws if no files are found under `sourceDir` (nothing to deploy).
+ */
+export declare function buildCar(sourceDir: string): Promise<BuiltCar>;
+/**
+ * Build a CAR for `sourceDir` and write it to `outPath`.
+ *
+ * A thin convenience over {@link buildCar} for the deploy path that persists a
+ * CAR to disk before importing it into each node. Returns the same
+ * {@link BuiltCar} (its `carBytes` are exactly the bytes written).
+ */
+export declare function writeCar(sourceDir: string, outPath: string): Promise<BuiltCar>;
+//# sourceMappingURL=car-build.d.ts.map

package/dist/car/car-build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"car-build.d.ts","sourceRoot":"","sources":["../../src/car/car-build.ts"],"names":[],"mappings":"AAmCA,kFAAkF;AAClF,MAAM,WAAW,QAAQ;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAqDnE;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC7B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACb,OAAO,CAAC,QAAQ,CAAC,CAInB"}

package/dist/car/car-build.js

@@ -0,0 +1,113 @@
+/**
+ * In-process **CAR** (Content Addressable aRchive) builder — the default and
+ * primary deploy artifact (CONTEXT.md `CAR`; spec user stories 4-6).
+ *
+ * Given a site SOURCE DIRECTORY, this builds a CAR whose root is a real UnixFS
+ * DIRECTORY preserving the site structure (`index.html`, `assets/...`). The DAG
+ * is built entirely IN-PROCESS via the `ipfs-car` library (no external CLI, no
+ * output scraping), so the root CID is authoritative and the build reproducible.
+ *
+ * The scheme (ported, not copied, from the reference prototype
+ * `~/searches/ipfs-hetzner/deploy-car.mjs`):
+ *
+ *   1. `filesFromPaths([sourceDir])` yields the directory's files with
+ *      SITE-RELATIVE paths (`index.html`, `assets/s.css`) and NO wrapping
+ *      segment. We pass them straight in: the CAR root IS the site dir. (An
+ *      earlier prototype wrongly stripped a leading segment; that bug is fixed
+ *      here and guarded by a test asserting `index.html` sits at the root.)
+ *   2. Pipe the files through `createDirectoryEncoderStream`, buffering every
+ *      emitted block and capturing the LAST block's CID as the directory root
+ *      (authoritative — captured from the encoder, NEVER scraped from text).
+ *   3. Re-encode the buffered blocks with `new CAREncoderStream([rootCid])` so
+ *      the CAR HEADER carries the root. That is what makes
+ *      `dag/import?pin-roots=true` pin the site root on every node.
+ *
+ * The build BUFFERS blocks in memory (fine for normal static sites; streaming
+ * very large sites is explicitly out of scope for v1 — see the spec).
+ */
+import { writeFile } from 'node:fs/promises';
+import { createDirectoryEncoderStream, CAREncoderStream, } from 'ipfs-car';
+import { filesFromPaths } from 'files-from-path';
+/**
+ * Build a CAR for a site source directory, entirely in-process.
+ *
+ * @param sourceDir the site's built output directory (its CONTENTS become the
+ *   CAR root — the directory itself is NOT wrapped in an extra segment).
+ * @returns the CAR bytes plus the authoritative root CID (the last block the
+ *   directory encoder emits, mirrored into the CAR header).
+ * @throws if no files are found under `sourceDir` (nothing to deploy).
+ */
+export async function buildCar(sourceDir) {
+    // filesFromPaths([sourceDir]) already yields SITE-RELATIVE paths
+    // ("index.html", "assets/s.css"). Do NOT strip a leading segment.
+    const files = await filesFromPaths([sourceDir]);
+    if (files.length === 0) {
+        throw new Error(`no files found under ${sourceDir}`);
+    }
+    // Pass 1: encode the directory, buffering blocks and capturing the root CID
+    // as the LAST emitted block. The header roots are patched in pass 2, so we
+    // encode with an empty root list here and discard the resulting stream.
+    const blocks = [];
+    let rootBlock;
+    await createDirectoryEncoderStream(files)
+        .pipeThrough(new TransformStream({
+        transform(block, controller) {
+            // The directory root is the LAST block the encoder emits.
+            rootBlock = block;
+            blocks.push(block);
+            controller.enqueue(block);
+        },
+    }))
+        .pipeThrough(new CAREncoderStream([]))
+        .pipeTo(new WritableStream());
+    if (!rootBlock) {
+        // Unreachable given files.length > 0, but keeps the root authoritative.
+        throw new Error(`encoder produced no blocks for ${sourceDir}`);
+    }
+    const rootCid = rootBlock.cid.toString();
+    // Pass 2: re-encode the SAME buffered blocks WITH the known root in the CAR
+    // header, so `dag/import?pin-roots=true` pins the site root.
+    const chunks = [];
+    const pending = blocks.slice();
+    const source = new ReadableStream({
+        pull(controller) {
+            const next = pending.shift();
+            if (next)
+                controller.enqueue(next);
+            else
+                controller.close();
+        },
+    });
+    await source.pipeThrough(new CAREncoderStream([rootBlock.cid])).pipeTo(new WritableStream({
+        write(chunk) {
+            chunks.push(chunk);
+        },
+    }));
+    return { carBytes: concatChunks(chunks), rootCid };
+}
+/**
+ * Build a CAR for `sourceDir` and write it to `outPath`.
+ *
+ * A thin convenience over {@link buildCar} for the deploy path that persists a
+ * CAR to disk before importing it into each node. Returns the same
+ * {@link BuiltCar} (its `carBytes` are exactly the bytes written).
+ */
+export async function writeCar(sourceDir, outPath) {
+    const built = await buildCar(sourceDir);
+    await writeFile(outPath, built.carBytes);
+    return built;
+}
+/** Concatenate CAR stream chunks into one contiguous byte array. */
+function concatChunks(chunks) {
+    let total = 0;
+    for (const chunk of chunks)
+        total += chunk.length;
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+//# sourceMappingURL=car-build.js.map

package/dist/car/car-build.js.map

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

package/dist/ci/ci-emit.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The **CI emitter** behind the `CIProvider` seam (CONTEXT.md `CI provider
+ * seam`). `install-ci` asks the core for a deploy pipeline: an emitter WRITES a
+ * deploy workflow for a CI system and REPORTS the repo secrets/vars the
+ * operator must set. GitHub Actions is the FIRST (and, in v1, only)
+ * implementation; other CI systems are Out of Scope but slot in behind this
+ * same seam later (spec "Out of Scope"; user stories 16, 17).
+ *
+ * This module is PURE: {@link emitCi} takes a plain input and returns the
+ * workflow file (path + contents) plus the secrets/vars report as data. It does
+ * NOT touch the filesystem or the network — the CLI wrapper (`cli-command-
+ * wrapper` task) is what writes the file to `.github/workflows/` and prints the
+ * report. Keeping the emit pure lets it be snapshot-tested as a string with no
+ * fixtures (test-first policy) and reused as a TypeScript API (CONTEXT.md `core
+ * vs cli`).
+ *
+ * BEHAVIOUR PORTED (not copied) from the reference GitHub Action
+ * `~/searches/ipfs-hetzner/github-workflow.yml`: the shape is checkout ->
+ * setup-node -> install -> build -> a `deploy` step reading the multi-node env
+ * contract (`IPFS_API`/`IPFS_TOKEN` comma-separated, publisher first),
+ * `SITE_NAME`, `SITE_MODE` -> a run-summary. Two deliberate CORRECTIONS vs the
+ * reference: (1) the deploy step invokes `pinnace deploy` (this tool now OWNS
+ * deploy) instead of a copied `deploy-car.mjs` script — one implementation, no
+ * bash/TS drift; (2) the same env contract carries the MULTI-NODE + per-site
+ * `mode` semantics (same CID to all nodes; the publisher publishes the record,
+ * replicas mirror) which the deploy core (`deploy-multi-target` +
+ * `publisher-replica-model` tasks) enforces — the workflow just passes the env
+ * through.
+ */
+/** The CI systems pinnace can emit for. v1 = GitHub Actions ONLY. */
+export type CiSystem = 'github';
+/** The CI systems, in a stable order (help text / iteration / validation). */
+export declare const CI_SYSTEMS: readonly CiSystem[];
+/** One required repo secret or variable the operator must set for the pipeline. */
+export interface RequiredCiSetting {
+    /** The env/secret/var NAME as referenced in the workflow (e.g. `IPFS_API`). */
+    name: string;
+    /**
+     * `secret` (masked, e.g. tokens) or `var` (plain repo variable, e.g. URLs /
+     * names). GitHub stores these separately; the report tells the operator
+     * which panel each belongs in.
+     */
+    kind: 'secret' | 'var';
+    /** A human-readable note (what it is, format, an example). */
+    description: string;
+    /**
+     * True when the value is a COMMA-SEPARATED list, one per target node with
+     * the PUBLISHER FIRST (the multi-node contract). `IPFS_API`/`IPFS_TOKEN` are
+     * multi-node; `SITE_NAME`/`SITE_MODE` are single values.
+     */
+    multiNode: boolean;
+    /** An example value, shown in the report to make the format concrete. */
+    example: string;
+}
+/** Inputs to {@link emitCi}: which system + how the site builds. */
+export interface EmitCiInput {
+    /** Which CI system to emit for (v1: `github`). */
+    system: CiSystem;
+    /** The build command that produces the static output dir (e.g. `npm run build`). */
+    buildCommand: string;
+    /** The directory the build outputs the static site to (e.g. `dist`). */
+    outputDir: string;
+    /** The branch to deploy on push (default `main`). */
+    branch?: string;
+    /** The Node.js version the workflow sets up (default `20`). */
+    nodeVersion?: string;
+}
+/** A single emitted file: where it goes + what it contains. */
+export interface EmittedFile {
+    /** The repo-relative path to write the file at. */
+    path: string;
+    /** The full file contents. */
+    contents: string;
+}
+/**
+ * What an emitter returns: the workflow file plus the secrets/vars the operator
+ * must set. `secrets` and `vars` are split so the CLI can tell the operator
+ * exactly which GitHub settings panel each value belongs in.
+ */
+export interface EmittedCi {
+    /** Which system this was emitted for (echoed for the caller). */
+    system: CiSystem;
+    /** The deploy workflow file (path + contents). */
+    workflow: EmittedFile;
+    /** The required masked SECRETS (Settings -> Secrets). */
+    secrets: RequiredCiSetting[];
+    /** The required repo VARIABLES (Settings -> Variables). */
+    vars: RequiredCiSetting[];
+}
+/**
+ * The `CIProvider` seam: one method that emits a deploy pipeline + its required
+ * settings for a given input. v1 has a single implementation
+ * ({@link githubCiProvider}); adding GitLab CI / others later means adding
+ * another provider here and an entry in {@link CI_SYSTEMS} — deploy/publish
+ * logic is untouched (spec user story 21).
+ */
+export interface CIProvider {
+    /** The system this provider emits for. */
+    readonly system: CiSystem;
+    /** Emit the workflow + secrets/vars report for the given input. */
+    emit(input: EmitCiInput): EmittedCi;
+}
+/**
+ * The GitHub Actions provider — the first implementation of {@link CIProvider}.
+ * Emits the deploy workflow to the conventional GitHub path and reports the
+ * secrets/vars split into the two GitHub settings panels.
+ */
+export declare const githubCiProvider: CIProvider;
+/**
+ * Emit a deploy pipeline for the requested CI system: dispatches to the
+ * matching {@link CIProvider} and returns its workflow + secrets/vars report.
+ * Throws LOUDLY on an unknown/unimplemented system (the seam exists so callers
+ * can add systems later, but v1 only ships `github`) — never a silent no-op.
+ */
+export declare function emitCi(input: EmitCiInput): EmittedCi;
+//# sourceMappingURL=ci-emit.d.ts.map

package/dist/ci/ci-emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-emit.d.ts","sourceRoot":"","sources":["../../src/ci/ci-emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,qEAAqE;AACrE,MAAM,MAAM,QAAQ,GAAG,QAAQ,CAAC;AAEhC,8EAA8E;AAC9E,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAAe,CAAC;AAE1D,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IACjC,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,EAAE,QAAQ,GAAG,KAAK,CAAC;IACvB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC3B,kDAAkD;IAClD,MAAM,EAAE,QAAQ,CAAC;IACjB,oFAAoF;IACpF,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,+DAA+D;AAC/D,MAAM,WAAW,WAAW;IAC3B,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACzB,iEAAiE;IACjE,MAAM,EAAE,QAAQ,CAAC;IACjB,kDAAkD;IAClD,QAAQ,EAAE,WAAW,CAAC;IACtB,yDAAyD;IACzD,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,2DAA2D;IAC3D,IAAI,EAAE,iBAAiB,EAAE,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IAC1B,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,mEAAmE;IACnE,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,CAAC;CACpC;AAsID;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,UAa9B,CAAC;AAOF;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,CAUpD"}

package/dist/ci/ci-emit.js

@@ -0,0 +1,190 @@
+/**
+ * The **CI emitter** behind the `CIProvider` seam (CONTEXT.md `CI provider
+ * seam`). `install-ci` asks the core for a deploy pipeline: an emitter WRITES a
+ * deploy workflow for a CI system and REPORTS the repo secrets/vars the
+ * operator must set. GitHub Actions is the FIRST (and, in v1, only)
+ * implementation; other CI systems are Out of Scope but slot in behind this
+ * same seam later (spec "Out of Scope"; user stories 16, 17).
+ *
+ * This module is PURE: {@link emitCi} takes a plain input and returns the
+ * workflow file (path + contents) plus the secrets/vars report as data. It does
+ * NOT touch the filesystem or the network — the CLI wrapper (`cli-command-
+ * wrapper` task) is what writes the file to `.github/workflows/` and prints the
+ * report. Keeping the emit pure lets it be snapshot-tested as a string with no
+ * fixtures (test-first policy) and reused as a TypeScript API (CONTEXT.md `core
+ * vs cli`).
+ *
+ * BEHAVIOUR PORTED (not copied) from the reference GitHub Action
+ * `~/searches/ipfs-hetzner/github-workflow.yml`: the shape is checkout ->
+ * setup-node -> install -> build -> a `deploy` step reading the multi-node env
+ * contract (`IPFS_API`/`IPFS_TOKEN` comma-separated, publisher first),
+ * `SITE_NAME`, `SITE_MODE` -> a run-summary. Two deliberate CORRECTIONS vs the
+ * reference: (1) the deploy step invokes `pinnace deploy` (this tool now OWNS
+ * deploy) instead of a copied `deploy-car.mjs` script — one implementation, no
+ * bash/TS drift; (2) the same env contract carries the MULTI-NODE + per-site
+ * `mode` semantics (same CID to all nodes; the publisher publishes the record,
+ * replicas mirror) which the deploy core (`deploy-multi-target` +
+ * `publisher-replica-model` tasks) enforces — the workflow just passes the env
+ * through.
+ */
+/** The CI systems, in a stable order (help text / iteration / validation). */
+export const CI_SYSTEMS = ['github'];
+/**
+ * The multi-node + per-site-mode env contract, shared by the reported
+ * secrets/vars and the workflow's deploy step (single source so they never
+ * drift). Order is stable: publisher-first multi-node inputs, then the site
+ * name/mode. `IPFS_TOKEN` is the sole secret; the rest are plain vars.
+ */
+const IPFS_API_SETTING = {
+    name: 'IPFS_API',
+    kind: 'var',
+    multiNode: true,
+    description: 'Kubo RPC endpoint(s). One URL, or comma-separated for MULTIPLE nodes ' +
+        '(publisher first, replicas after). Same CID lands on every node.',
+    example: 'https://ipfs-a.you.com,https://ipfs-b.you.com',
+};
+const IPFS_TOKEN_SETTING = {
+    name: 'IPFS_TOKEN',
+    kind: 'secret',
+    multiNode: true,
+    description: 'Bearer token(s) guarding the RPC API. One token, or comma-separated ' +
+        'tokens in the SAME order as IPFS_API (publisher first).',
+    example: 'tokenA,tokenB',
+};
+const SITE_NAME_SETTING = {
+    name: 'SITE_NAME',
+    kind: 'var',
+    multiNode: false,
+    description: 'The site name / ENS name this deploy targets.',
+    example: 'mysite.eth',
+};
+const SITE_MODE_SETTING = {
+    name: 'SITE_MODE',
+    kind: 'var',
+    multiNode: false,
+    description: "Per-site mode: 'ipfs' (immutable, ENS ipfs://<cid> per deploy) or " +
+        "'ipns' (mutable, publisher publishes the record, replicas mirror). " +
+        "Defaults to 'ipns'.",
+    example: 'ipns',
+};
+/** All settings in report order (drives both the report split and validation). */
+const ALL_SETTINGS = [
+    IPFS_API_SETTING,
+    IPFS_TOKEN_SETTING,
+    SITE_NAME_SETTING,
+    SITE_MODE_SETTING,
+];
+/**
+ * Render the GitHub Actions deploy workflow. Ports the reference Action's shape
+ * (checkout -> setup-node -> install -> build -> deploy reading the env
+ * contract -> run summary), but the deploy step calls `pinnace deploy` (this
+ * tool owns deploy) and the env carries the multi-node + per-site-mode
+ * semantics the deploy core enforces. Deterministic: same input -> byte-
+ * identical output (snapshot-locked).
+ */
+function renderGithubWorkflow(input) {
+    const branch = input.branch ?? 'main';
+    const nodeVersion = input.nodeVersion ?? '20';
+    const buildCommand = input.buildCommand;
+    const outputDir = input.outputDir;
+    return `# =============================================================================
+# pinnace: deploy a static site to your self-hosted IPFS node(s) on push.
+#
+# Generated by \`pinnace install-ci --system github\`. Edit BUILD/OUTPUT below
+# for your stack; the deploy step is owned by the \`pinnace\` CLI.
+#
+# Set these in your repo (Settings -> Secrets and variables -> Actions):
+#   IPFS_API    (variable) one URL, OR comma-separated for MULTIPLE nodes,
+#               publisher first (e.g. https://ipfs-a.you.com,https://ipfs-b.you.com)
+#   IPFS_TOKEN  (secret)   matching token(s), comma-separated in the SAME order
+#   SITE_NAME   (variable) e.g. mysite.eth
+#   SITE_MODE   (variable) ipfs | ipns  (default ipns)
+#
+# Multiple nodes serve the SAME CID (redundancy). In ipns mode the PUBLISHER
+# (first in IPFS_API) publishes the signed record; replicas mirror it.
+# =============================================================================
+name: Deploy to IPFS
+
+on:
+  push:
+    branches: [${branch}]
+  workflow_dispatch: {}
+
+concurrency:
+  group: pinnace-deploy
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${nodeVersion}
+          cache: npm
+
+      - name: Install deps
+        run: npm ci
+
+      - name: Build
+        run: ${buildCommand}
+
+      - name: Deploy to IPFS node(s)
+        id: deploy
+        env:
+          IPFS_API: \${{ vars.IPFS_API }}
+          IPFS_TOKEN: \${{ secrets.IPFS_TOKEN }}
+          SITE_NAME: \${{ vars.SITE_NAME }}
+          SITE_MODE: \${{ vars.SITE_MODE || 'ipns' }}
+        run: |
+          npx pinnace deploy --mode "$SITE_MODE" "${outputDir}" "$SITE_NAME"
+
+      - name: Summary
+        if: always()
+        run: |
+          echo "### IPFS deploy" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "- CID:  \\\`\${{ steps.deploy.outputs.cid }}\\\`" >> "$GITHUB_STEP_SUMMARY"
+          echo "- IPNS: \\\`\${{ steps.deploy.outputs.ipns }}\\\`" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Preview: https://\${{ steps.deploy.outputs.cid }}.ipfs.dweb.link/" >> "$GITHUB_STEP_SUMMARY"
+`;
+}
+/**
+ * The GitHub Actions provider — the first implementation of {@link CIProvider}.
+ * Emits the deploy workflow to the conventional GitHub path and reports the
+ * secrets/vars split into the two GitHub settings panels.
+ */
+export const githubCiProvider = {
+    system: 'github',
+    emit(input) {
+        return {
+            system: 'github',
+            workflow: {
+                path: '.github/workflows/pinnace-deploy.yml',
+                contents: renderGithubWorkflow(input),
+            },
+            secrets: ALL_SETTINGS.filter((s) => s.kind === 'secret'),
+            vars: ALL_SETTINGS.filter((s) => s.kind === 'var'),
+        };
+    },
+};
+/** The provider registry (system -> provider). v1 has a single entry. */
+const PROVIDERS = {
+    github: githubCiProvider,
+};
+/**
+ * Emit a deploy pipeline for the requested CI system: dispatches to the
+ * matching {@link CIProvider} and returns its workflow + secrets/vars report.
+ * Throws LOUDLY on an unknown/unimplemented system (the seam exists so callers
+ * can add systems later, but v1 only ships `github`) — never a silent no-op.
+ */
+export function emitCi(input) {
+    const provider = PROVIDERS[input.system];
+    if (!provider) {
+        throw new Error(`unsupported CI system '${input.system}'; v1 emits only ${CI_SYSTEMS.join(', ')} (other systems are Out of Scope but the CIProvider seam exists)`);
+    }
+    return provider.emit(input);
+}
+//# sourceMappingURL=ci-emit.js.map

package/dist/ci/ci-emit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-emit.js","sourceRoot":"","sources":["../../src/ci/ci-emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAKH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,UAAU,GAAwB,CAAC,QAAQ,CAAC,CAAC;AA4E1D;;;;;GAKG;AACH,MAAM,gBAAgB,GAAsB;IAC3C,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,KAAK;IACX,SAAS,EAAE,IAAI;IACf,WAAW,EACV,uEAAuE;QACvE,kEAAkE;IACnE,OAAO,EAAE,+CAA+C;CACxD,CAAC;AAEF,MAAM,kBAAkB,GAAsB;IAC7C,IAAI,EAAE,YAAY;IAClB,IAAI,EAAE,QAAQ;IACd,SAAS,EAAE,IAAI;IACf,WAAW,EACV,sEAAsE;QACtE,yDAAyD;IAC1D,OAAO,EAAE,eAAe;CACxB,CAAC;AAEF,MAAM,iBAAiB,GAAsB;IAC5C,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,KAAK;IACX,SAAS,EAAE,KAAK;IAChB,WAAW,EAAE,+CAA+C;IAC5D,OAAO,EAAE,YAAY;CACrB,CAAC;AAEF,MAAM,iBAAiB,GAAsB;IAC5C,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,KAAK;IACX,SAAS,EAAE,KAAK;IAChB,WAAW,EACV,oEAAoE;QACpE,qEAAqE;QACrE,qBAAqB;IACtB,OAAO,EAAE,MAAM;CACf,CAAC;AAEF,kFAAkF;AAClF,MAAM,YAAY,GAAiC;IAClD,gBAAgB;IAChB,kBAAkB;IAClB,iBAAiB;IACjB,iBAAiB;CACjB,CAAC;AAEF;;;;;;;GAOG;AACH,SAAS,oBAAoB,CAAC,KAAkB;IAC/C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC;IACtC,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,IAAI,IAAI,CAAC;IAC9C,MAAM,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;IACxC,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;IAElC,OAAO;;;;;;;;;;;;;;;;;;;;iBAoBS,MAAM;;;;;;;;;;;;;;;0BAeG,WAAW;;;;;;;eAOtB,YAAY;;;;;;;;;;oDAUyB,SAAS;;;;;;;;;;CAU5D,CAAC;AACF,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAe;IAC3C,MAAM,EAAE,QAAQ;IAChB,IAAI,CAAC,KAAkB;QACtB,OAAO;YACN,MAAM,EAAE,QAAQ;YAChB,QAAQ,EAAE;gBACT,IAAI,EAAE,sCAAsC;gBAC5C,QAAQ,EAAE,oBAAoB,CAAC,KAAK,CAAC;aACrC;YACD,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC;YACxD,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC;SAClD,CAAC;IACH,CAAC;CACD,CAAC;AAEF,yEAAyE;AACzE,MAAM,SAAS,GAAiC;IAC/C,MAAM,EAAE,gBAAgB;CACxB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,KAAkB;IACxC,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACd,0BAA0B,KAAK,CAAC,MAAM,oBAAoB,UAAU,CAAC,IAAI,CACxE,IAAI,CACJ,kEAAkE,CACnE,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC7B,CAAC"}

package/dist/cli/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/cli/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":""}

package/dist/cli/bin.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * The `pinnace` CLI bin — a thin wrapper over the library core.
+ *
+ * It parses/formats only; ALL behaviour lives in the core (imported from
+ * `../index.js`). It wires the client verbs (provision, deploy, install-ci,
+ * status, derive) over the injectable `RunContext` seam in `./run.ts`; the
+ * on-box `pinnace node <verb>` subcommands share this same binary but are wired
+ * by their own task. Config/env/core are all injectable there so the dispatch
+ * is unit-tested without a process or the operator's real env/config.
+ */
+import { run } from './run.js';
+run(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});
+//# sourceMappingURL=bin.js.map

package/dist/cli/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG;AACH,OAAO,EAAC,GAAG,EAAC,MAAM,UAAU,CAAC;AAE7B,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAC9B,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAC5B,CAAC,GAAG,EAAE,EAAE;IACP,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAChE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjB,CAAC,CACD,CAAC"}

package/dist/cli/run.d.ts

@@ -0,0 +1,78 @@
+import { type ProvisionInput, type ProvisionResult } from '../provision/cloud-init.js';
+import { type DeployInput, type DeployResult } from '../deploy/deploy.js';
+import { type EmitCiInput, type EmittedCi } from '../ci/ci-emit.js';
+import { type StatusReportInput, type StatusReport } from '../status/status-report.js';
+import { type DeriveIpnsInput } from '../derive/ipns-key-derivation.js';
+import { type PinnaceConfigFile, type EnvRecord } from '../config/config-resolution.js';
+/**
+ * The core functions the client verbs dispatch to. This seam is what makes the
+ * CLI a THIN wrapper AND independently testable: production wires the real core
+ * ({@link DEFAULT_DEPS}); tests inject recording stubs and assert each verb
+ * calls the RIGHT function with the correctly-resolved arguments (rather than
+ * re-testing the core through the CLI).
+ */
+export interface ClientDeps {
+    /** `provision` -> the cloud-init generator. */
+    provision(input: ProvisionInput): ProvisionResult;
+    /** `deploy` -> the multi-target CAR deploy. */
+    deploy(input: DeployInput): Promise<DeployResult>;
+    /** `install-ci` -> the CI workflow emitter. */
+    emitCi(input: EmitCiInput): EmittedCi;
+    /** `status` -> the per-site status report. */
+    statusReport(input: StatusReportInput): Promise<StatusReport>;
+    /** `derive` -> the master + site `id` -> IPNS id derivation (no deploy). */
+    deriveIpnsId(input: DeriveIpnsInput): string;
+}
+/**
+ * The CLI run context: the injectable env/config/output/core seams. Everything
+ * is optional; omitted fields default to the real process environment, a real
+ * `pinnace.json` read, `console` sinks, and the real core. Tests pass explicit
+ * in-memory values to stay hermetic.
+ */
+export interface RunContext {
+    /** The env layer (defaults to `process.env`). Tests pass an in-memory record. */
+    env?: EnvRecord;
+    /**
+     * Load the parsed config file (defaults to reading `./pinnace.json`, or an
+     * empty config if absent). Tests pass an in-memory object.
+     *
+     * `path` is the operator's explicit `--config <path>` when given, else
+     * `undefined` (the `./pinnace.json` default). The default loader treats an
+     * ABSENT default file as a benign empty config, but an explicitly-named path
+     * that is missing / unreadable / invalid JSON must THROW so `run()` can fail
+     * loud naming that path (an operator-named file is a claim it exists).
+     */
+    loadConfigFile?: (path?: string) => PinnaceConfigFile;
+    /** The core functions to dispatch to (defaults to the real core). */
+    deps?: ClientDeps;
+    /** stdout sink (defaults to `console.log`). */
+    out?: (line: string) => void;
+    /** stderr sink (defaults to `console.error`). */
+    err?: (line: string) => void;
+}
+/**
+ * An explicitly-named `--config <path>` could not be read or parsed. Names the
+ * path so `run()` can emit a loud, operator-actionable error (exit 1) instead
+ * of silently resolving to an empty config.
+ */
+export declare class ConfigLoadError extends Error {
+    readonly path: string;
+    readonly kind: 'read' | 'parse';
+    constructor(path: string, kind: 'read' | 'parse', cause?: unknown);
+}
+/**
+ * Dispatch a pinnace CLI invocation. Returns the process exit code.
+ *
+ * Routes the client verbs (provision/deploy/install-ci/status/derive), the
+ * on-box `node` namespace, and the `site` namespace. A missing command is a
+ * benign no-op (exit 0); an UNKNOWN command is loud (exit 1) so the surface is
+ * an explicit allow-list, not a silent catch-all.
+ *
+ * A GLOBAL `--config <path>` flag may appear BEFORE the command; it is consumed
+ * here (stripped from the per-verb argv) and threaded into config loading via
+ * the {@link RunContext.loadConfigFile} seam. With no `--config`, the default
+ * `./pinnace.json` is read and its absence is benign; an explicitly-named path
+ * that is missing/unreadable/invalid JSON fails loud (names the path, exit 1).
+ */
+export declare function run(argv: readonly string[], context?: RunContext): Promise<number>;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AA0BA,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,eAAe,EAEpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAEN,KAAK,WAAW,EAChB,KAAK,YAAY,EAEjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEN,KAAK,WAAW,EAChB,KAAK,SAAS,EAEd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAEN,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAEN,KAAK,eAAe,EACpB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAKN,KAAK,iBAAiB,EACtB,KAAK,SAAS,EAId,MAAM,gCAAgC,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IAC1B,+CAA+C;IAC/C,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CAAC;IAClD,+CAA+C;IAC/C,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAClD,+CAA+C;IAC/C,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,CAAC;IACtC,8CAA8C;IAC9C,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC9D,4EAA4E;IAC5E,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC;CAC7C;AAWD;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B,iFAAiF;IACjF,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,iBAAiB,CAAC;IACtD,qEAAqE;IACrE,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,+CAA+C;IAC/C,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,iDAAiD;IACjD,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AA8CD;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IAExC,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;gBADtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GAAG,OAAO,EAC/B,KAAK,CAAC,EAAE,OAAO;CAMhB;AAoBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,GAAG,CACxB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,GAAE,UAAe,GACtB,OAAO,CAAC,MAAM,CAAC,CAkDjB"}