pinnace 0.0.0 → 0.2.0

package/dist/site/site-management.js

@@ -0,0 +1,123 @@
+/** The verbs, in a stable order (for help text / iteration). */
+export const SITE_VERBS = ['list', 'remove', 'add'];
+/** The MFS directory sites live under. */
+const DEFAULT_SITES_DIR = '/sites';
+/**
+ * **list** — enumerate the sites the node currently serves (MFS `/sites/*`),
+ * annotating each with its current CID (from `files/stat`) and, when a keystore
+ * key of the same name exists, its IPNS id (from `key/list -l`). A fresh box
+ * with no `/sites` dir yields an empty list, not an error.
+ */
+export async function listSites(input) {
+    const sitesDir = input.sitesDir ?? DEFAULT_SITES_DIR;
+    const entries = await lsSites(input.client, sitesDir);
+    if (entries.length === 0)
+        return [];
+    const keys = await listKeys(input.client);
+    const sites = [];
+    for (const id of entries) {
+        const cid = await statCid(input.client, `${sitesDir}/${id}`);
+        if (!cid)
+            continue; // an entry with no resolvable CID is skipped, not fatal.
+        sites.push({ id, cid, ipns: keys.get(id) });
+    }
+    return sites;
+}
+/**
+ * **remove** — delete a site: `files/rm /sites/<name>` FIRST (so it immediately
+ * drops out of MFS auto-discovery and stops being served/announced/warmed),
+ * THEN `pin/rm <cid>` to unpin the content so its storage is reclaimed. The CID
+ * is resolved up-front with `files/stat` so we know what to unpin after the
+ * entry is gone.
+ *
+ * The MFS removal is the load-bearing step and is always attempted. The unpin
+ * is best-effort: if the content was never pinned (or is pinned indirectly),
+ * `pin/rm` errors, which is REPORTED (`unpinned: false`) rather than thrown, so
+ * a partially-pinned site still removes cleanly.
+ */
+export async function removeSite(input) {
+    const sitesDir = input.sitesDir ?? DEFAULT_SITES_DIR;
+    const path = `${sitesDir}/${input.id}`;
+    // Resolve the CID before we remove the entry (afterwards it is gone).
+    const cid = await statCid(input.client, path);
+    // Remove the MFS entry first: it stops being discovered/served/announced.
+    await input.client.filesRm(path, { recursive: true, force: true });
+    // Then reclaim storage by unpinning the content. Best-effort: a site that
+    // was never pinned (or pinned indirectly) must not fail the removal.
+    let unpinned = false;
+    if (cid) {
+        try {
+            await input.client.pinRm(cid);
+            unpinned = true;
+        }
+        catch {
+            unpinned = false;
+        }
+    }
+    return { id: input.id, cid, unpinned };
+}
+/**
+ * **add** — expose an existing CID as a served site by placing it into MFS at
+ * `/sites/<name>` (the discoverable location warm/republish/status read). This
+ * is deploy's MFS-placement step in isolation (see the module DESIGN NOTE): it
+ * does NOT build or import a CAR and does NOT pin (the CID is assumed already
+ * imported/pinned on the node).
+ */
+export async function addSite(input) {
+    const sitesDir = input.sitesDir ?? DEFAULT_SITES_DIR;
+    await placeInMfs(input.client, sitesDir, input.id, input.cid);
+    return { id: input.id, cid: input.cid };
+}
+/**
+ * The MFS-placement step: `files/mkdir /sites --parents`, `files/rm
+ * /sites/<id> --recursive --force` (clear any prior content), then `files/cp
+ * /ipfs/<cid> /sites/<id>`. Ported from the reference prototype's deploy MFS
+ * placement (`~/searches/ipfs-hetzner/deploy-car.mjs`). Exported so `deploy`
+ * can REUSE this exact sequence rather than forking it.
+ */
+export async function placeInMfs(client, sitesDir, id, cid) {
+    await client.filesMkdir(sitesDir, { parents: true });
+    await client.filesRm(`${sitesDir}/${id}`, { recursive: true, force: true });
+    await client.filesCp(`/ipfs/${cid}`, `${sitesDir}/${id}`);
+}
+// ---------------------------------------------------------------------------
+// Small shared Kubo reads (fail-soft where a missing dir is not an error).
+// ---------------------------------------------------------------------------
+/** List the entry NAMES under the sites dir; empty on a fresh box (no dir). */
+async function lsSites(client, sitesDir) {
+    let listing;
+    try {
+        listing = await client.filesLs(sitesDir);
+    }
+    catch {
+        // No /sites dir yet (fresh box) — nothing to list, not an error.
+        return [];
+    }
+    const names = [];
+    for (const entry of listing.Entries ?? []) {
+        if (entry?.Name)
+            names.push(entry.Name);
+    }
+    return names;
+}
+/** Stat an MFS path for its current CID, or undefined if it cannot be resolved. */
+async function statCid(client, path) {
+    try {
+        const stat = await client.filesStat(path);
+        return stat?.Hash;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Map site/key name -> IPNS id from `key/list -l` (same shape as node-commands). */
+async function listKeys(client) {
+    const res = await client.keyList();
+    const map = new Map();
+    for (const k of res.Keys ?? []) {
+        if (k?.Name && k?.Id)
+            map.set(k.Name, k.Id);
+    }
+    return map;
+}
+//# sourceMappingURL=site-management.js.map

package/dist/site/site-management.js.map

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

package/dist/status/status-report.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The `status` core operation — pinnace's discoverability VERIFICATION surface
+ * (CONTEXT.md `gateway warming`; spec user story 18).
+ *
+ * For every site auto-discovered from MFS `/sites/*` (over the Kubo RPC seam) it
+ * reports FOUR fields so an operator can confirm a deploy actually landed
+ * everywhere:
+ *
+ *   1. current CID        — `files/stat --hash` (via {@link discoverSites}).
+ *   2. IPNS id            — from `key/list -l` IF a key of the SAME name exists
+ *                           (ipfs-mode sites have none).
+ *   3. network-announce   — does the NETWORK announce THIS node for the CID? The
+ *                           external delegated-routing providers list for the
+ *                           CID contains this node's PeerID (`id`).
+ *   4. gateway-serves     — does a COLD public gateway serve it? An HTTP
+ *                           range/HEAD result from a public gateway.
+ *
+ * The two checks in (3) and (4) reach OUTSIDE the node. They are INJECTABLE
+ * ({@link ProvidersLookup}, {@link GatewayProbe}) so tests run against a fake
+ * HTTP layer and never the live network; production supplies the default
+ * `fetch`-backed implementations below.
+ *
+ * Behaviour ported (NOT copied) from the reference prototype
+ * `~/searches/ipfs-hetzner/status.sh`: the delegated-routing providers lookup at
+ * `https://delegated-ipfs.dev/routing/v1/providers/<cid>` (does
+ * `.Providers[].ID` include our PeerID?) and the
+ * `https://<cid>.ipfs.dweb.link/` range-request cold-gateway probe. The shell's
+ * `jq .Providers[].ID == $PEERID` and `curl -r 0-0 -w %{http_code}` shapes
+ * become the two TS predicates here.
+ *
+ * SEAM NOTE: this module OWNS the per-site status checks; the on-box `status`
+ * verb (`../node/node-commands.ts`) consumes them via its injectable
+ * `NodeCommandOps.status` seam — {@link makeStatusOp} adapts this core into that
+ * seam. The dashboard persistence (`status.json`) is the command layer's job,
+ * not this module's: this module PRODUCES the report and stops.
+ *
+ * A failed external check is a REPORTED outcome, never a throw: a
+ * delegated-routing lookup that errors reports `announced=false` (not findable
+ * right now) and a gateway probe that errors reports `gatewayServes=false`. One
+ * cold gateway or one flaky routing endpoint must not fail the whole report.
+ */
+import { type DiscoveredSite } from '../node/node-commands.js';
+import type { KuboRpcClient } from '../rpc/kubo-rpc-client.js';
+import type { NodeCommandContext, NodeOpResult } from '../node/node-commands.js';
+/**
+ * The subset of the delegated-routing `/routing/v1/providers/<cid>` JSON we
+ * read: the `Providers` array, each with an `ID` (a PeerID). Other fields are
+ * ignored.
+ */
+export interface ProvidersResponse {
+    Providers?: Array<{
+        ID?: string;
+    }> | null;
+}
+/**
+ * An injectable delegated-routing providers lookup: given a CID, return the
+ * providers response (whose `.Providers[].ID` we scan for our PeerID). Tests
+ * inject a fake; production uses {@link defaultProvidersLookup}. Throwing is
+ * treated as "not findable" (announced=false), never propagated.
+ */
+export type ProvidersLookup = (cid: string) => Promise<ProvidersResponse>;
+/**
+ * An injectable cold-gateway probe: given a CID, return the HTTP status a
+ * public gateway responds with (a 2xx/206 means it served). Tests inject a
+ * fake; production uses {@link defaultGatewayProbe}. Throwing is treated as
+ * "did not serve" (gatewayServes=false), never propagated.
+ */
+export type GatewayProbe = (cid: string) => Promise<number>;
+/** The status of one site: the four report fields plus its `id`. */
+export interface SiteStatus {
+    /** The site's single `id` (its MFS entry under `/sites/`). */
+    id: string;
+    /** The current content root CID (`files/stat --hash`). */
+    cid: string;
+    /** The IPNS id, if a same-named keystore key exists (else undefined). */
+    ipns?: string;
+    /** True when the delegated-routing providers list for the CID has our PeerID. */
+    announced: boolean;
+    /** The HTTP status the cold public gateway probe returned (undefined on error). */
+    gatewayHttp?: number;
+    /** True when the gateway probe status indicates the CID was served (2xx/206). */
+    gatewayServes: boolean;
+}
+/** The full status report: this node's PeerID plus a per-site status line. */
+export interface StatusReport {
+    /** This node's PeerID (from Kubo `id`); the announce check looks for it. */
+    peerId: string;
+    /** One {@link SiteStatus} per site discovered under MFS `/sites/*`. */
+    sites: SiteStatus[];
+}
+/** Inputs to {@link statusReport}. */
+export interface StatusReportInput {
+    /** The Kubo RPC client for THIS node (files/ls, files/stat, key/list, id). */
+    client: KuboRpcClient;
+    /** The MFS directory sites live under (default `/sites`). */
+    sitesDir?: string;
+    /**
+     * The delegated-routing providers lookup (injectable; defaults to the live
+     * `delegated-ipfs.dev` fetch via {@link defaultProvidersLookup}).
+     */
+    providersLookup?: ProvidersLookup;
+    /**
+     * The cold-gateway probe (injectable; defaults to the live `dweb.link`
+     * range-request via {@link defaultGatewayProbe}).
+     */
+    gatewayProbe?: GatewayProbe;
+    /**
+     * Pre-discovered sites (optional). When set, discovery is SKIPPED and these
+     * are used as-is — the node-command layer already walked MFS, so the adapter
+     * ({@link makeStatusOp}) passes them straight through rather than re-listing.
+     */
+    sites?: DiscoveredSite[];
+}
+/**
+ * Build the per-site status report. Discovers sites (unless supplied), reads
+ * this node's PeerID and its keystore once, then for each site runs the two
+ * external checks (through the injected/default fakes) to fill the four fields.
+ * External-check failures degrade to `false`, never throw.
+ */
+export declare function statusReport(input: StatusReportInput): Promise<StatusReport>;
+/**
+ * Adapt {@link statusReport} into a {@link NodeCommandContext} `status` op so
+ * the on-box `status` verb can inject it (its `ops.status` seam). The command
+ * layer discovers sites and passes them in; this adapter runs the four-field
+ * checks over them and flattens the result into a {@link NodeOpResult} (its
+ * per-site outcomes carry the announce + gateway outcomes too).
+ */
+export declare function makeStatusOp(checks?: {
+    providersLookup?: ProvidersLookup;
+    gatewayProbe?: GatewayProbe;
+}): (ctx: NodeCommandContext, sites: DiscoveredSite[]) => Promise<NodeOpResult>;
+/**
+ * The default delegated-routing lookup: GET
+ * `https://delegated-ipfs.dev/routing/v1/providers/<cid>` and parse its JSON.
+ * (Injected fakes replace this in tests; it is the only place the live routing
+ * endpoint is named.)
+ */
+export declare const defaultProvidersLookup: ProvidersLookup;
+/**
+ * The default cold-gateway probe: a single-byte range request to
+ * `https://<cid>.ipfs.dweb.link/` returning the HTTP status. (Injected fakes
+ * replace this in tests; it is the only place the live gateway is named.)
+ */
+export declare const defaultGatewayProbe: GatewayProbe;
+//# sourceMappingURL=status-report.d.ts.map

package/dist/status/status-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-report.d.ts","sourceRoot":"","sources":["../../src/status/status-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,EAAgB,KAAK,cAAc,EAAC,MAAM,0BAA0B,CAAC;AAC5E,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,2BAA2B,CAAC;AAC7D,OAAO,KAAK,EAAC,kBAAkB,EAAE,YAAY,EAAC,MAAM,0BAA0B,CAAC;AAS/E;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC,SAAS,CAAC,EAAE,KAAK,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,GAAG,IAAI,CAAC;CACxC;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE5D,oEAAoE;AACpE,MAAM,WAAW,UAAU;IAC1B,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAC;IACZ,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,SAAS,EAAE,OAAO,CAAC;IACnB,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,aAAa,EAAE,OAAO,CAAC;CACvB;AAED,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC5B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,KAAK,EAAE,UAAU,EAAE,CAAC;CACpB;AAED,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IACjC,8EAA8E;IAC9E,MAAM,EAAE,aAAa,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CACjC,KAAK,EAAE,iBAAiB,GACtB,OAAO,CAAC,YAAY,CAAC,CAwBvB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC3B,MAAM,GAAE;IAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAAC,YAAY,CAAC,EAAE,YAAY,CAAA;CAAM,GAC3E,CAAC,GAAG,EAAE,kBAAkB,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,OAAO,CAAC,YAAY,CAAC,CAqB7E;AA6ED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,eAMpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,YAKjC,CAAC"}

package/dist/status/status-report.js

@@ -0,0 +1,192 @@
+/**
+ * The `status` core operation — pinnace's discoverability VERIFICATION surface
+ * (CONTEXT.md `gateway warming`; spec user story 18).
+ *
+ * For every site auto-discovered from MFS `/sites/*` (over the Kubo RPC seam) it
+ * reports FOUR fields so an operator can confirm a deploy actually landed
+ * everywhere:
+ *
+ *   1. current CID        — `files/stat --hash` (via {@link discoverSites}).
+ *   2. IPNS id            — from `key/list -l` IF a key of the SAME name exists
+ *                           (ipfs-mode sites have none).
+ *   3. network-announce   — does the NETWORK announce THIS node for the CID? The
+ *                           external delegated-routing providers list for the
+ *                           CID contains this node's PeerID (`id`).
+ *   4. gateway-serves     — does a COLD public gateway serve it? An HTTP
+ *                           range/HEAD result from a public gateway.
+ *
+ * The two checks in (3) and (4) reach OUTSIDE the node. They are INJECTABLE
+ * ({@link ProvidersLookup}, {@link GatewayProbe}) so tests run against a fake
+ * HTTP layer and never the live network; production supplies the default
+ * `fetch`-backed implementations below.
+ *
+ * Behaviour ported (NOT copied) from the reference prototype
+ * `~/searches/ipfs-hetzner/status.sh`: the delegated-routing providers lookup at
+ * `https://delegated-ipfs.dev/routing/v1/providers/<cid>` (does
+ * `.Providers[].ID` include our PeerID?) and the
+ * `https://<cid>.ipfs.dweb.link/` range-request cold-gateway probe. The shell's
+ * `jq .Providers[].ID == $PEERID` and `curl -r 0-0 -w %{http_code}` shapes
+ * become the two TS predicates here.
+ *
+ * SEAM NOTE: this module OWNS the per-site status checks; the on-box `status`
+ * verb (`../node/node-commands.ts`) consumes them via its injectable
+ * `NodeCommandOps.status` seam — {@link makeStatusOp} adapts this core into that
+ * seam. The dashboard persistence (`status.json`) is the command layer's job,
+ * not this module's: this module PRODUCES the report and stops.
+ *
+ * A failed external check is a REPORTED outcome, never a throw: a
+ * delegated-routing lookup that errors reports `announced=false` (not findable
+ * right now) and a gateway probe that errors reports `gatewayServes=false`. One
+ * cold gateway or one flaky routing endpoint must not fail the whole report.
+ */
+import { discoverSites } from '../node/node-commands.js';
+/** The delegated-routing providers endpoint (path takes the CID). */
+const DELEGATED_ROUTING_BASE = 'https://delegated-ipfs.dev/routing/v1/providers';
+/** The public gateway used for the cold-serve probe (`<cid>.ipfs.<host>`). */
+const DWEB_LINK_HOST = 'ipfs.dweb.link';
+/**
+ * Build the per-site status report. Discovers sites (unless supplied), reads
+ * this node's PeerID and its keystore once, then for each site runs the two
+ * external checks (through the injected/default fakes) to fill the four fields.
+ * External-check failures degrade to `false`, never throw.
+ */
+export async function statusReport(input) {
+    const sitesDir = input.sitesDir ?? '/sites';
+    const providersLookup = input.providersLookup ?? defaultProvidersLookup;
+    const gatewayProbe = input.gatewayProbe ?? defaultGatewayProbe;
+    const sites = input.sites ?? (await discoverSites(input.client, sitesDir));
+    const peerId = await readPeerId(input.client);
+    const keys = await listKeys(input.client);
+    const statuses = [];
+    for (const site of sites) {
+        const announced = await checkAnnounced(providersLookup, site.cid, peerId);
+        const gatewayHttp = await probeGateway(gatewayProbe, site.cid);
+        statuses.push({
+            id: site.id,
+            cid: site.cid,
+            ipns: keys.get(site.id),
+            announced,
+            gatewayHttp,
+            gatewayServes: gatewayHttp !== undefined && servesStatus(gatewayHttp),
+        });
+    }
+    return { peerId, sites: statuses };
+}
+/**
+ * Adapt {@link statusReport} into a {@link NodeCommandContext} `status` op so
+ * the on-box `status` verb can inject it (its `ops.status` seam). The command
+ * layer discovers sites and passes them in; this adapter runs the four-field
+ * checks over them and flattens the result into a {@link NodeOpResult} (its
+ * per-site outcomes carry the announce + gateway outcomes too).
+ */
+export function makeStatusOp(checks = {}) {
+    return async (ctx, sites) => {
+        const report = await statusReport({
+            client: ctx.client,
+            sitesDir: ctx.sitesDir,
+            sites,
+            providersLookup: checks.providersLookup,
+            gatewayProbe: checks.gatewayProbe,
+        });
+        return {
+            sites: report.sites.map((s) => ({
+                id: s.id,
+                cid: s.cid,
+                ipns: s.ipns ?? '',
+                announced: s.announced,
+                gatewayServes: s.gatewayServes,
+                gatewayHttp: s.gatewayHttp,
+                status: s.gatewayServes && s.announced ? 'ok' : 'unverified',
+            })),
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// Per-site checks (fail-soft).
+// ---------------------------------------------------------------------------
+/**
+ * Ask delegated routing who provides the CID and answer: is OUR PeerID among
+ * them? A lookup error is "not findable right now" -> false, never thrown (one
+ * flaky routing endpoint must not fail the report). Ports the shell's
+ * `jq '.Providers[]|select(.ID==$p)'`.
+ */
+async function checkAnnounced(lookup, cid, peerId) {
+    if (!peerId)
+        return false;
+    try {
+        const res = await lookup(cid);
+        return (res.Providers ?? []).some((p) => p?.ID === peerId);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Probe a cold public gateway for the CID and return its HTTP status, or
+ * undefined if the probe itself errored (network down, DNS, ...). Ports the
+ * shell's `curl -r 0-0 -w %{http_code}`.
+ */
+async function probeGateway(probe, cid) {
+    try {
+        return await probe(cid);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A gateway HTTP status counts as "served" iff it is 2xx (including 206). */
+function servesStatus(status) {
+    return status >= 200 && status < 300;
+}
+// ---------------------------------------------------------------------------
+// Kubo reads.
+// ---------------------------------------------------------------------------
+/** Read this node's PeerID from Kubo `id` (empty string if unavailable). */
+async function readPeerId(client) {
+    try {
+        const res = await client.id();
+        return res?.ID ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+/** Map site/key name -> IPNS id from `key/list -l` (same shape as node-commands). */
+async function listKeys(client) {
+    const res = await client.keyList();
+    const map = new Map();
+    for (const k of res.Keys ?? []) {
+        if (k?.Name && k?.Id)
+            map.set(k.Name, k.Id);
+    }
+    return map;
+}
+// ---------------------------------------------------------------------------
+// Default (LIVE) external checks. Production wiring; tests inject fakes instead.
+// ---------------------------------------------------------------------------
+/**
+ * The default delegated-routing lookup: GET
+ * `https://delegated-ipfs.dev/routing/v1/providers/<cid>` and parse its JSON.
+ * (Injected fakes replace this in tests; it is the only place the live routing
+ * endpoint is named.)
+ */
+export const defaultProvidersLookup = async (cid) => {
+    const res = await fetch(`${DELEGATED_ROUTING_BASE}/${cid}`, {
+        headers: { accept: 'application/json' },
+    });
+    if (!res.ok)
+        return { Providers: [] };
+    return (await res.json());
+};
+/**
+ * The default cold-gateway probe: a single-byte range request to
+ * `https://<cid>.ipfs.dweb.link/` returning the HTTP status. (Injected fakes
+ * replace this in tests; it is the only place the live gateway is named.)
+ */
+export const defaultGatewayProbe = async (cid) => {
+    const res = await fetch(`https://${cid}.${DWEB_LINK_HOST}/`, {
+        headers: { range: 'bytes=0-0' },
+    });
+    return res.status;
+};
+//# sourceMappingURL=status-report.js.map

package/dist/status/status-report.js.map

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

package/package.json

@@ -1,4 +1,47 @@
 {
   "name": "pinnace",
-  "version": "0.0.0"
-}
+  "version": "0.2.0",
+  "license": "AGPL-3.0-only",
+  "description": "Self-host a static website on IPFS across one or more self-owned Kubo nodes.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wighawag/pinnace.git",
+    "directory": "packages/pinnace"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "pinnace": "./dist/cli/bin.js"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "files-from-path": "^1.1.4",
+    "ipfs-car": "^3.1.0"
+  },
+  "devDependencies": {
+    "@ipld/car": "^5.4.6",
+    "@ipld/dag-pb": "^4.1.7",
+    "@types/node": "^25.2.0",
+    "as-soon": "^0.1.5",
+    "tsx": "^4.21.0",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "as-soon -w src pnpm build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/car/car-build.ts

@@ -0,0 +1,135 @@
+/**
+ * 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,
+	type Block,
+} from 'ipfs-car';
+import {filesFromPaths} from 'files-from-path';
+
+/** 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 async function buildCar(sourceDir: string): Promise<BuiltCar> {
+	// 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: Block[] = [];
+	let rootBlock: Block | undefined;
+	await createDirectoryEncoderStream(files)
+		.pipeThrough(
+			new TransformStream({
+				transform(block: 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: Uint8Array[] = [];
+	const pending = blocks.slice();
+	const source = new ReadableStream<Block>({
+		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: string,
+	outPath: string,
+): Promise<BuiltCar> {
+	const built = await buildCar(sourceDir);
+	await writeFile(outPath, built.carBytes);
+	return built;
+}
+
+/** Concatenate CAR stream chunks into one contiguous byte array. */
+function concatChunks(chunks: Uint8Array[]): Uint8Array {
+	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;
+}