pinnace 0.0.0 → 0.2.0

package/README.md

@@ -0,0 +1,164 @@
+# pinnace
+
+Self-host a static website on IPFS across one or more self-owned Kubo nodes, without a paid pinning service. `pinnace` provisions the nodes (generated cloud-init), deploys your site as a content-addressed archive pinned on every node with the same CID, manages mutable `ipns://` names via a master-key-derived per-site key, keeps public-gateway caches warm, and emits CI, all over the nodes' bearer-guarded Kubo RPC API. Hetzner is the first host; other hosts sit behind a provider seam.
+
+`pinnace` is both a **CLI** and a **library**: the core owns all logic and the `pinnace` bin is a thin wrapper, so every operation is equally usable as a TypeScript API.
+
+## Install
+
+```sh
+npm install -g pinnace
+# or, per-project:
+npm install pinnace
+```
+
+Requires Node >= 22.
+
+## Mental model
+
+- **node** (box): a self-owned server running the Kubo IPFS daemon, reached ONLY via its Kubo RPC API (`POST /api/v0/...`, bearer-token guarded, fronted by Caddy over HTTPS). Swarm port 4001 is open so public gateways can dial it; the raw RPC (5001) is never exposed.
+- **publisher / replica**: exactly one **publisher** per shared IPNS name holds the derived key, signs + refreshes the record, and exports the raw signed record. Keyless **replicas** pin the same CID and re-announce the publisher's record (falling back to a cached copy if the publisher is down). This is the failover model: the name stays resolvable within the record's validity window even if the publisher dies.
+- **CID / CAR**: your site is built client-side into a CAR (Content Addressable aRchive) whose root is the site's UnixFS directory; the same CAR is imported into every node so they all serve the identical **CID**.
+- **master key -> per-site IPNS key**: one operator-held secret (env-only, never on a node, never in the config file) deterministically derives each site's IPNS key: `HKDF-SHA256(master, info = "pinnace:ipns:v1:" + id)` -> ed25519 seed -> the `k51...` IPNS name. Names are recoverable from the master alone; provisioning is stateless. This is a frozen contract (see the ADRs).
+- **site `id`**: one value per site, used as BOTH its MFS entry (`/sites/<id>`) AND the key-derivation input. Pick anything stable (e.g. `mysite`, or `ronan.eth`).
+- **mode**: per-site `ipfs` (land + pin + MFS only; you point a contenthash at `ipfs://<cid>` per deploy) or `ipns` (also publish/refresh; point it at `ipns://<id>` once).
+- **gateway warming**: re-fetching each site's CID through public gateways so their caches stay hot; sites are auto-discovered from MFS.
+
+## Configuration + secrets
+
+Every setting resolves **CLI arg > env (via `ldenv`) > `pinnace.json`**.
+
+`pinnace.json` holds only NON-secret structure (commit-safe):
+
+```json
+{
+  "hosts": [
+    { "name": "publisher", "endpoint": "https://ipfs-publisher.example.com", "role": "publisher" },
+    { "name": "replica", "endpoint": "https://ipfs-replica-01.example.com", "role": "replica",
+      "publisherEndpoint": "https://ipfs-dash.example.com" }
+  ],
+  "sites": [
+    { "id": "mysite", "mode": "ipns", "sourceDir": "./site" }
+  ]
+}
+```
+
+Secrets are **env-only, never in the config file** (structurally: the resolver has no file path for them). Each host's bearer token is read from `PINNACE_HOST_<NAME>_TOKEN` (the name upper-cased), and the master from `PINNACE_MASTER`:
+
+```sh
+# .env.local (git-ignored) — the ONLY place secrets live
+PINNACE_MASTER=<your high-entropy master secret>
+PINNACE_HOST_PUBLISHER_TOKEN=<publisher bearer token>
+PINNACE_HOST_REPLICA_TOKEN=<replica bearer token>
+```
+
+A missing token fails loud (naming the exact env var), never a silent empty token. Point the CLI at a config anywhere with `--config <path>`.
+
+## The end-to-end setup
+
+The full flow, from zero to a redundant, failover-capable IPNS site. Values below match the config above; substitute your own domains.
+
+### 1. Pick tokens + an id
+
+```sh
+export PINNACE_HOST_PUBLISHER_TOKEN=$(openssl rand -hex 32)
+export PINNACE_HOST_REPLICA_TOKEN=$(openssl rand -hex 32)
+# choose one id for the site, used as both the MFS entry and the key input
+```
+
+### 2. Generate cloud-init for each box
+
+`provision` emits ready-to-paste cloud-init to stdout (it is per-box and arg-driven; it does not read `pinnace.json`). Give the publisher a `--dashboard-domain`: that vhost serves the exported IPNS records at `/records/` for replicas to fetch.
+
+```sh
+# publisher
+pinnace provision --host hetzner --role publisher \
+  --api-domain ipfs-publisher.example.com \
+  --dashboard-domain ipfs-dash.example.com \
+  --acme-email you@example.com \
+  --bearer-token "$PINNACE_HOST_PUBLISHER_TOKEN" > cloud-init-publisher.yaml
+
+# replica (points at the publisher's DASHBOARD as its records endpoint)
+pinnace provision --host hetzner --role replica \
+  --api-domain ipfs-replica-01.example.com \
+  --acme-email you@example.com \
+  --bearer-token "$PINNACE_HOST_REPLICA_TOKEN" \
+  --publisher-endpoint https://ipfs-dash.example.com > cloud-init-replica.yaml
+```
+
+The emitted cloud-init stands up a hardened node: Kubo as a systemd unit (discoverability tuned so gateways find it), ufw opening 4001 TCP+UDP + 80/443 (never 5001), Caddy HTTPS + bearer API proxy, and it installs a pinned `pinnace` on the box and schedules the on-box agent (`pinnace node republish|mirror|warm|status`) on role-gated systemd timers. The publisher's `republish` timer exports signed records to the dashboard's `/records/`; the replica's `mirror` timer fetches + re-announces them, falling back to cache on outage.
+
+### 3. Create the boxes + DNS
+
+Create two servers (e.g. Hetzner Debian 13 / CX22), each with its `cloud-init-*.yaml` as user-data. Then point DNS at their IPv4s so Caddy can obtain certificates:
+
+```
+A  ipfs-publisher    <publisher IP>
+A  ipfs-replica-01   <replica IP>
+A  ipfs-dash         <publisher IP>     # the records/dashboard vhost
+```
+
+Verify each API answers once DNS + certs are up (bearer required):
+
+```sh
+curl -sS -X POST https://ipfs-publisher.example.com/api/v0/id \
+  -H "Authorization: Bearer $PINNACE_HOST_PUBLISHER_TOKEN"
+```
+
+### 4. Derive the IPNS id (optional, before first deploy)
+
+Print a site's `k51...` id from the master + id with no deploy or network, so you can set a contenthash ahead of time:
+
+```sh
+pinnace --config pinnace.json derive mysite
+```
+
+### 5. Deploy + provision the publisher key
+
+```sh
+# build one CAR, import the same CID into every node, place it in MFS
+pinnace --config pinnace.json deploy --mode ipns ./site mysite
+
+# import the derived key onto the publisher (and flip its role to publisher)
+pinnace --config pinnace.json promote mysite --host publisher
+```
+
+After this the on-box timers run the failover loop automatically: the publisher re-signs + exports the record, replicas mirror + re-announce it, and if the publisher goes down the replicas keep the name alive from their cached record within its validity window.
+
+### 6. Check it
+
+```sh
+pinnace --config pinnace.json status                 # per-site CID / IPNS id / announce / gateway-serves
+curl -sS https://ipfs-dash.example.com/records/mysite.ipns-record   # the exported signed record
+```
+
+## Command reference
+
+| Command | What it does |
+| --- | --- |
+| `pinnace provision --host hetzner --role <publisher\|replica> --api-domain <d> --acme-email <e> --bearer-token <t> [--dashboard-domain <d>] [--publisher-endpoint <url>]` | Emit a node's cloud-init YAML to stdout. |
+| `pinnace deploy [--mode ipfs\|ipns] <dir> <id>` | Build one CAR, import the same CID into every configured node, pin + place in MFS; in `ipns` mode publish on the publisher. |
+| `pinnace promote <id> [--host <name>]` | Derive the per-site key from the master and import it onto the host, making it the publisher (also the replica-promotion path). |
+| `pinnace derive <id>` (alias `ipns-id`) | Print a site's `k51...` IPNS id from master + id, no deploy/network. |
+| `pinnace status` | Per-site report across nodes: CID, IPNS id, network-announce, gateway-serves. |
+| `pinnace install-ci --system github --build-command <c> --output-dir <d>` | Emit a deploy CI workflow and report the secrets/vars to set. |
+| `pinnace site <list\|add\|remove> ...` | Manage the sites a node serves (MFS entries + pins). |
+| `pinnace node <republish\|mirror\|warm\|status>` | The on-box agent verbs (run by the box's systemd timers; role-gated). |
+
+Global: `--config <path>` selects the `pinnace.json` (default `./pinnace.json`); a named-but-missing path fails loud.
+
+## Library use
+
+Every operation is exported from the package core, so the same things are callable as a TypeScript API:
+
+```ts
+import {deriveIpnsId, buildCar, resolveConfig, KuboRpcClient} from 'pinnace';
+```
+
+## Design notes / decisions
+
+Durable architectural decisions live in [`docs/adr/`](../../docs/adr/) in the repo, notably: the frozen master-key -> IPNS KDF; that client-side key derivation is NOT client-side record signing (the node signs); and the boundary that Kubo owns pinning + provider-record freshness while the same `pinnace` binary runs the recurring on-box loop.
+
+## License
+
+AGPL-3.0-only.

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"}