@inharness-ai/claude4spec 1.0.7 → 1.0.8

package/dist/server/services/release-bundle.js

@@ -0,0 +1,183 @@
+/**
+ * Portable bundle — the third representation of a spec (alongside live HEAD and
+ * versioned history). A `tar.gz` holding the full, self-contained state of a
+ * release N, derived ONLY from the versioning tables (via `getReleaseSnapshot`),
+ * never from `pagesDir` on disk or entity HEADs.
+ *
+ * Spec reference: brief `0-1-27-to-0-1-28.md`. Direct consumers (future):
+ * M25 (push to remote) writes; M26 (`c4s import`) reads. The restore direction
+ * lives in `ReleaseService.restoreBundleArchive` (contract-only in v1).
+ *
+ * This module owns the pure write logic + the constants/types M26 will import.
+ * The two public methods stay on `ReleaseService` per the M17 contract; they
+ * are thin delegations to `buildBundleArchive(...)` here.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import { create as tarCreate } from 'tar';
+import { nanoid } from 'nanoid';
+/**
+ * Bundle layout version. Bump = breaking change in the bundle shape (layout,
+ * manifest, sanitization semantics). M26 import compares
+ * `manifest.bundleSchemaVersion` against the highest version it supports →
+ * mismatch ⇒ `BUNDLE_SCHEMA_UNSUPPORTED`. NOT bumped when an entity's
+ * `serializer_version` changes — each bundle is self-contained w.r.t. entity
+ * schema (carried per-type in the manifest's `serializerVersions`).
+ */
+export const BUNDLE_SCHEMA_VERSION = 1;
+/**
+ * Strict singular entity type → plural bundle file name. Published for M26
+ * (read direction maps plural file → entity type via the reverse).
+ */
+export const ENTITY_TYPE_TO_PLURAL_FILE = {
+    endpoint: 'endpoints.json',
+    dto: 'dtos.json',
+    'database-table': 'database-tables.json',
+    'ui-view': 'ui-views.json',
+    ac: 'acs.json',
+};
+/** claude4spec version read once at module load (pattern from `src/bin/c4s-mcp.ts`). */
+function readC4sVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const candidates = [
+            path.resolve(here, '..', 'package.json'),
+            path.resolve(here, '..', '..', 'package.json'),
+            path.resolve(here, '..', '..', '..', 'package.json'),
+            path.resolve(here, '..', '..', '..', '..', 'package.json'),
+        ];
+        for (const pkgPath of candidates) {
+            if (fs.existsSync(pkgPath)) {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+                if (pkg.version)
+                    return pkg.version;
+            }
+        }
+    }
+    catch {
+        /* ignore — fall through to fallback */
+    }
+    return '0.0.0';
+}
+export const C4S_VERSION = readC4sVersion();
+/**
+ * Explicit allow-list (fail-closed). This is the ONLY edit point when M01 adds
+ * a new `Config` field: a new field is dropped from the bundle until someone
+ * consciously decides to keep it here. No allow-list entry → no leak.
+ */
+export function sanitizeConfigForBundle(config) {
+    return {
+        $schemaVersion: config.$schemaVersion,
+        name: config.name,
+        pagesDir: config.pagesDir,
+        mode: config.mode,
+        writingStyle: config.writingStyle,
+        onboardingCompleted: config.onboardingCompleted,
+        entities: config.entities,
+        agent: { claudeUsePreset: config.agent?.claudeUsePreset },
+    };
+}
+/** Recursively collect file entries under `dir`, as sorted posix-style relative paths. */
+function collectSortedEntries(dir) {
+    const out = [];
+    const walk = (abs, rel) => {
+        for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+            const childAbs = path.join(abs, entry.name);
+            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory())
+                walk(childAbs, childRel);
+            else
+                out.push(childRel);
+        }
+    };
+    walk(dir, '');
+    return out.sort();
+}
+/** Streaming SHA-256 over a file → lowercase hex64. */
+function sha256File(file) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash('sha256');
+        const stream = fs.createReadStream(file);
+        stream.on('error', reject);
+        stream.on('data', (chunk) => hash.update(chunk));
+        stream.on('end', () => resolve(hash.digest('hex')));
+    });
+}
+/**
+ * Build a portable `tar.gz` for release N from an already-resolved snapshot.
+ *
+ * Pure `(snapshot, release, config) → bytes` — no DB / disk reads beyond the
+ * temp working dir. The caller (`ReleaseService.buildBundleArchive`) resolves
+ * `snapshot`/`release` from the versioning tables and `config` via `readConfig`.
+ *
+ * Determinism: entries are sorted and tar headers use `portable` + `noMtime` to
+ * strip system-specific noise. The returned `sha256` is an integrity hash over
+ * the ACTUAL produced bytes (round-trip self-consistent) — gzip OS-byte/level
+ * differences mean it is NOT a cross-machine reproducible build hash.
+ *
+ * `tarGzPath` is NOT cleaned up here — the consumer (M25 push / M26 import /
+ * test) owns it. The internal temp dir IS cleaned up in `finally`.
+ */
+export async function buildBundleArchive(snapshot, release, config) {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'c4s-bundle-'));
+    try {
+        // 1. manifest.json
+        const manifest = {
+            bundleSchemaVersion: BUNDLE_SCHEMA_VERSION,
+            release: {
+                id: release.id,
+                name: release.name,
+                description: release.description,
+                createdAt: release.createdAt,
+            },
+            c4sVersion: C4S_VERSION,
+            createdAt: new Date().toISOString(),
+            serializerVersions: snapshot.serializer_versions,
+        };
+        fs.writeFileSync(path.join(tempDir, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
+        // 2. config.json (sanitized allow-list)
+        fs.writeFileSync(path.join(tempDir, 'config.json'), JSON.stringify(sanitizeConfigForBundle(config), null, 2), 'utf8');
+        // 3. pages/<path>.md — byte-equal content, skip delete tombstones.
+        for (const page of snapshot.pages) {
+            if (page.op === 'delete')
+                continue;
+            const data = page.data;
+            const dest = path.join(tempDir, 'pages', data.path);
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            fs.writeFileSync(dest, data.content, 'utf8');
+        }
+        // 4. entities/<typePlural>.json — one file per active type with rows.
+        const byType = new Map();
+        for (const entity of snapshot.entities) {
+            if (entity.op === 'delete')
+                continue;
+            const list = byType.get(entity.type) ?? [];
+            list.push(entity);
+            byType.set(entity.type, list);
+        }
+        if (byType.size > 0) {
+            const entitiesDir = path.join(tempDir, 'entities');
+            fs.mkdirSync(entitiesDir, { recursive: true });
+            for (const [type, rows] of byType) {
+                const fileName = ENTITY_TYPE_TO_PLURAL_FILE[type];
+                if (!fileName)
+                    continue; // defensively skip unknown types
+                fs.writeFileSync(path.join(entitiesDir, fileName), JSON.stringify(rows, null, 2), 'utf8');
+            }
+        }
+        // 5. tar -czf (sorted entries, portable headers for stable-ish output).
+        const tarGzPath = path.join(os.tmpdir(), `c4s-bundle-${nanoid()}.tar.gz`);
+        await tarCreate({ gzip: true, file: tarGzPath, cwd: tempDir, portable: true, noMtime: true }, collectSortedEntries(tempDir));
+        // 6. SHA-256 + size of the final archive.
+        const sha256 = await sha256File(tarGzPath);
+        const sizeBytes = fs.statSync(tarGzPath).size;
+        return { tarGzPath, sizeBytes, sha256, bundleSchemaVersion: BUNDLE_SCHEMA_VERSION };
+    }
+    finally {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=release-bundle.js.map

package/dist/server/services/release-bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-bundle.js","sourceRoot":"","sources":["../../../src/server/services/release-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,KAAK,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAKhC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAU,CAAC;AAEhD;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAA2B;IAChE,QAAQ,EAAE,gBAAgB;IAC1B,GAAG,EAAE,WAAW;IAChB,gBAAgB,EAAE,sBAAsB;IACxC,SAAS,EAAE,eAAe;IAC1B,EAAE,EAAE,UAAU;CACf,CAAC;AA0CF,wFAAwF;AACxF,SAAS,cAAc;IACrB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1D,MAAM,UAAU,GAAG;YACjB,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;YACxC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;YAC9C,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;YACpD,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;SAC3D,CAAC;QACF,KAAK,MAAM,OAAO,IAAI,UAAU,EAAE,CAAC;YACjC,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAyB,CAAC;gBACjF,IAAI,GAAG,CAAC,OAAO;oBAAE,OAAO,GAAG,CAAC,OAAO,CAAC;YACtC,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,uCAAuC;IACzC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;AAE5C;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAc;IACpD,OAAO;QACL,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,mBAAmB,EAAE,MAAM,CAAC,mBAAmB;QAC/C,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,KAAK,EAAE,EAAE,eAAe,EAAE,MAAM,CAAC,KAAK,EAAE,eAAe,EAAE;KAC1D,CAAC;AACJ,CAAC;AAED,0FAA0F;AAC1F,SAAS,oBAAoB,CAAC,GAAW;IACvC,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,IAAI,GAAG,CAAC,GAAW,EAAE,GAAW,EAAQ,EAAE;QAC9C,KAAK,MAAM,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;YACjE,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAC5C,MAAM,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;YAC3D,IAAI,KAAK,CAAC,WAAW,EAAE;gBAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;;gBAC7C,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC,CAAC;IACF,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACd,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;AACpB,CAAC;AAED,uDAAuD;AACvD,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;QAClC,MAAM,MAAM,GAAG,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC3B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACjD,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,QAAsB,EACtB,OAAgB,EAChB,MAAc;IAEd,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC;IACtE,IAAI,CAAC;QACH,mBAAmB;QACnB,MAAM,QAAQ,GAAmB;YAC/B,mBAAmB,EAAE,qBAAqB;YAC1C,OAAO,EAAE;gBACP,EAAE,EAAE,OAAO,CAAC,EAAE;gBACd,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,SAAS,EAAE,OAAO,CAAC,SAAS;aAC7B;YACD,UAAU,EAAE,WAAW;YACvB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,kBAAkB,EAAE,QAAQ,CAAC,mBAAmB;SACjD,CAAC;QACF,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QAEjG,wCAAwC;QACxC,EAAE,CAAC,aAAa,CACd,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,EACjC,IAAI,CAAC,SAAS,CAAC,uBAAuB,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EACxD,MAAM,CACP,CAAC;QAEF,mEAAmE;QACnE,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YAClC,IAAI,IAAI,CAAC,EAAE,KAAK,QAAQ;gBAAE,SAAS;YACnC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAwB,CAAC;YAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;YACpD,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACtD,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC/C,CAAC;QAED,sEAAsE;QACtE,MAAM,MAAM,GAAG,IAAI,GAAG,EAAmC,CAAC;QAC1D,KAAK,MAAM,MAAM,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;YACvC,IAAI,MAAM,CAAC,EAAE,KAAK,QAAQ;gBAAE,SAAS;YACrC,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YAC3C,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAClB,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAChC,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YACpB,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YACnD,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/C,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,EAAE,CAAC;gBAClC,MAAM,QAAQ,GAAG,0BAA0B,CAAC,IAAI,CAAC,CAAC;gBAClD,IAAI,CAAC,QAAQ;oBAAE,SAAS,CAAC,iCAAiC;gBAC1D,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YAC5F,CAAC;QACH,CAAC;QAED,wEAAwE;QACxE,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,cAAc,MAAM,EAAE,SAAS,CAAC,CAAC;QAC1E,MAAM,SAAS,CACb,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,EAC5E,oBAAoB,CAAC,OAAO,CAAC,CAC9B,CAAC;QAEF,0CAA0C;QAC1C,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,SAAS,CAAC,CAAC;QAC3C,MAAM,SAAS,GAAG,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC;QAE9C,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,CAAC;IACtF,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACvD,CAAC;AACH,CAAC"}

package/dist/server/services/release-push.d.ts

@@ -0,0 +1,38 @@
+/**
+ * M25 Release Push — service-owner of the `release_push` table and the push flow.
+ *
+ * `push(releaseId)` is a COORDINATOR: it gates on the M24 session, delegates the
+ * bundle build to M17 (`releaseService.buildBundleArchive`), transports it via the
+ * M24 client (`remoteAuth.pushBundle`), records the attempt, and cleans up. It
+ * never builds the bundle itself — there are intentionally NO `tar`/`gzip`/
+ * `archiver`/`crypto.createHash` imports here (grep-checkable, AC m25).
+ *
+ * Every completed attempt (success OR error) is an append-only INSERT; in-progress
+ * attempts are not persisted. Retry = a new INSERT (no UPDATE, no DELETE).
+ *
+ * Spec: brief 0-1-28-to-0-1-29.md (M25).
+ */
+import type Database from 'better-sqlite3';
+import type { ReleaseService } from './release.js';
+import type { RemoteAuthService } from './remote-auth.js';
+import type { ReleasePushResponse } from '../../shared/release-push.js';
+export declare class ReleasePushService {
+    private db;
+    private releaseService;
+    private remoteAuth;
+    private cwd;
+    constructor(db: Database.Database, releaseService: ReleaseService, remoteAuth: RemoteAuthService, cwd: string);
+    /**
+     * Synchronous push of release N to the remote. Algorithm (brief §1.3):
+     * gate → validate release → build bundle (M17) → transport (M24) → persist →
+     * cleanup. The bundle's `tarGzPath` is unlinked in `finally` ALWAYS (M17 does
+     * not clean it up — the consumer owns it).
+     */
+    push(releaseId: number): Promise<ReleasePushResponse>;
+    /** Audit log for one release, newest first (uses idx_release_push_release_id). */
+    listForRelease(releaseId: number): ReleasePushResponse[];
+    getById(id: number): ReleasePushResponse | null;
+    /** Forward-looking — the whole audit log, newest first. */
+    listAll(): ReleasePushResponse[];
+    private insertRow;
+}

package/dist/server/services/release-push.js

@@ -0,0 +1,179 @@
+/**
+ * M25 Release Push — service-owner of the `release_push` table and the push flow.
+ *
+ * `push(releaseId)` is a COORDINATOR: it gates on the M24 session, delegates the
+ * bundle build to M17 (`releaseService.buildBundleArchive`), transports it via the
+ * M24 client (`remoteAuth.pushBundle`), records the attempt, and cleans up. It
+ * never builds the bundle itself — there are intentionally NO `tar`/`gzip`/
+ * `archiver`/`crypto.createHash` imports here (grep-checkable, AC m25).
+ *
+ * Every completed attempt (success OR error) is an append-only INSERT; in-progress
+ * attempts are not persisted. Retry = a new INSERT (no UPDATE, no DELETE).
+ *
+ * Spec: brief 0-1-28-to-0-1-29.md (M25).
+ */
+import { unlink } from 'node:fs/promises';
+import { DomainError } from './tags.js';
+import { readConfig, writeConfig } from '../config.js';
+import { RemoteUnauthorizedError, RemoteRequestError } from './remote-http-client.js';
+/** Shared projection — the row plus the local release name (saves the UI a fetch). */
+const SELECT_WITH_RELEASE = `SELECT rp.*, sr.name AS release_name
+     FROM release_push rp
+     JOIN spec_release sr ON sr.id = rp.release_id`;
+export class ReleasePushService {
+    db;
+    releaseService;
+    remoteAuth;
+    cwd;
+    constructor(db, releaseService, remoteAuth, cwd) {
+        this.db = db;
+        this.releaseService = releaseService;
+        this.remoteAuth = remoteAuth;
+        this.cwd = cwd;
+    }
+    /**
+     * Synchronous push of release N to the remote. Algorithm (brief §1.3):
+     * gate → validate release → build bundle (M17) → transport (M24) → persist →
+     * cleanup. The bundle's `tarGzPath` is unlinked in `finally` ALWAYS (M17 does
+     * not clean it up — the consumer owns it).
+     */
+    async push(releaseId) {
+        // 1. Gate (M24). Snapshot identity here so it survives a 401 mid-push (which
+        //    wipes remote_session) — the audit row still records who attempted it.
+        const account = this.remoteAuth.getCurrentAccount();
+        if (!account.connected) {
+            throw new DomainError('NOT_CONNECTED', 'Connect to the remote server before pushing');
+        }
+        if (account.accountStatus !== 'active') {
+            throw new DomainError('ACCOUNT_NOT_ACTIVE', 'Account deactivated — push is blocked');
+        }
+        const accountId = account.remoteAccountId ?? '';
+        const accountEmail = account.accountEmail ?? null;
+        // 2. Validate the local release exists (frozen releases are allowed).
+        try {
+            this.releaseService.getRelease(releaseId);
+        }
+        catch (err) {
+            if (err instanceof DomainError && err.code === 'NOT_FOUND') {
+                throw new DomainError('RELEASE_NOT_FOUND', `release '${releaseId}' not found`);
+            }
+            throw err;
+        }
+        // 3. Build the bundle (M17). All bytes-derived values come from here.
+        const bundle = await this.releaseService.buildBundleArchive(releaseId);
+        const config = readConfig(this.cwd);
+        const firstPush = config.remoteProjectId == null;
+        try {
+            let outcome;
+            try {
+                // 4. Transport (M24 injects the Bearer; handles 401 → session wipe).
+                outcome = await this.remoteAuth.pushBundle({
+                    tarGzPath: bundle.tarGzPath,
+                    sizeBytes: bundle.sizeBytes,
+                    sha256: bundle.sha256,
+                    projectName: config.name,
+                    remoteProjectId: config.remoteProjectId ?? null,
+                });
+            }
+            catch (err) {
+                // 5a. Error attempt → append an error row, then re-throw mapped to 502.
+                const sessionExpired = err instanceof RemoteUnauthorizedError;
+                const errorMessage = sessionExpired
+                    ? 'Session expired'
+                    : err instanceof RemoteRequestError
+                        ? err.message
+                        : 'Network error';
+                this.insertRow({
+                    releaseId,
+                    remoteProjectId: config.remoteProjectId ?? '',
+                    remoteReleaseId: null,
+                    remoteReleaseSequence: null,
+                    contentSha256: bundle.sha256,
+                    contentSizeBytes: bundle.sizeBytes,
+                    deduplicated: false,
+                    accountId,
+                    accountEmail,
+                    bundleSchemaVersion: bundle.bundleSchemaVersion,
+                    status: 'error',
+                    errorMessage,
+                });
+                throw new DomainError(sessionExpired ? 'SESSION_EXPIRED' : 'PUSH_FAILED', sessionExpired ? 'Session expired, log in and try again' : errorMessage);
+            }
+            // 5b. Success. On first push, persist the new remoteProjectId atomically
+            //     so subsequent pushes go to POST /v1/projects/:id/releases.
+            if (firstPush) {
+                writeConfig(this.cwd, { remoteProjectId: outcome.remoteProjectId });
+            }
+            const id = this.insertRow({
+                releaseId,
+                remoteProjectId: outcome.remoteProjectId,
+                remoteReleaseId: outcome.remoteReleaseId,
+                remoteReleaseSequence: outcome.remoteReleaseSequence,
+                contentSha256: bundle.sha256,
+                contentSizeBytes: bundle.sizeBytes,
+                deduplicated: outcome.deduplicated,
+                accountId,
+                accountEmail,
+                bundleSchemaVersion: bundle.bundleSchemaVersion,
+                status: 'success',
+                errorMessage: null,
+            });
+            return this.getById(id);
+        }
+        finally {
+            // 6. ALWAYS clean up the bundle the consumer owns.
+            await unlink(bundle.tarGzPath).catch(() => { });
+        }
+    }
+    /** Audit log for one release, newest first (uses idx_release_push_release_id). */
+    listForRelease(releaseId) {
+        const rows = this.db
+            .prepare(`${SELECT_WITH_RELEASE} WHERE rp.release_id = ? ORDER BY rp.pushed_at DESC, rp.id DESC`)
+            .all(releaseId);
+        return rows.map(toDto);
+    }
+    getById(id) {
+        const row = this.db
+            .prepare(`${SELECT_WITH_RELEASE} WHERE rp.id = ?`)
+            .get(id);
+        return row ? toDto(row) : null;
+    }
+    /** Forward-looking — the whole audit log, newest first. */
+    listAll() {
+        const rows = this.db
+            .prepare(`${SELECT_WITH_RELEASE} ORDER BY rp.pushed_at DESC, rp.id DESC`)
+            .all();
+        return rows.map(toDto);
+    }
+    insertRow(a) {
+        const info = this.db
+            .prepare(`INSERT INTO release_push
+           (release_id, remote_project_id, remote_release_id, remote_release_sequence,
+            content_sha256, content_size_bytes, deduplicated,
+            pushed_by_account_id, pushed_by_account_email, bundle_schema_version,
+            status, error_message)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(a.releaseId, a.remoteProjectId, a.remoteReleaseId, a.remoteReleaseSequence, a.contentSha256, a.contentSizeBytes, a.deduplicated ? 1 : 0, a.accountId, a.accountEmail, a.bundleSchemaVersion, a.status, a.errorMessage);
+        return Number(info.lastInsertRowid);
+    }
+}
+function toDto(row) {
+    return {
+        id: row.id,
+        releaseId: row.release_id,
+        release: { id: row.release_id, name: row.release_name },
+        remoteProjectId: row.remote_project_id,
+        remoteReleaseId: row.remote_release_id ?? undefined,
+        remoteReleaseSequence: row.remote_release_sequence ?? undefined,
+        contentSha256: row.content_sha256,
+        contentSizeBytes: row.content_size_bytes,
+        deduplicated: row.deduplicated === 1,
+        pushedByAccountId: row.pushed_by_account_id,
+        pushedByAccountEmail: row.pushed_by_account_email ?? undefined,
+        bundleSchemaVersion: row.bundle_schema_version,
+        status: row.status === 'error' ? 'error' : 'success',
+        errorMessage: row.error_message ?? undefined,
+        pushedAt: row.pushed_at,
+    };
+}
+//# sourceMappingURL=release-push.js.map

package/dist/server/services/release-push.js.map

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

package/dist/server/services/release.d.ts

@@ -18,6 +18,7 @@ import type { TagsService } from './tags.js';
 import type { PagesService } from './pages.js';
 import type { PagesWatcher } from '../fs/watcher.js';
 import type { RestoreResult } from '../serialization/types.js';
+import { type BuildBundleResult } from './release-bundle.js';
 export interface RestoreEntityInput {
     type: RawEntityType;
     slug: string;
@@ -56,9 +57,16 @@ export declare class ReleaseService {
     private tagsService;
     private pagesService;
     private watcher;
-    constructor(db: Database.Database, host: PluginHost, versions: VersionService, pageVersions: PageVersionService, pageSerializer: PageSerializer, rawReader: RawEntityReader, tagsService: TagsService, pagesService: PagesService, watcher?: PagesWatcher | null);
+    private cwd;
+    constructor(db: Database.Database, host: PluginHost, versions: VersionService, pageVersions: PageVersionService, pageSerializer: PageSerializer, rawReader: RawEntityReader, tagsService: TagsService, pagesService: PagesService, watcher?: PagesWatcher | null, cwd?: string);
     listReleases(): Release[];
     getRelease(idOrName: number | string): ReleaseDetail;
+    /**
+     * Count of captures still queued at HEAD — entity_version + page_version rows
+     * with `release_id IS NULL`. Drives the M25 "You have N unreleased changes"
+     * banner shown only on the latest (mutable) release card.
+     */
+    countUnreleased(): number;
     /**
      * Manual release creation (decyzja 9: zero auto-trigger). Validates
      * non-empty + UNIQUE name and non-empty description; in a single
@@ -119,6 +127,36 @@ export declare class ReleaseService {
      * pages. Each step generates normal mutations → all visible in timeline.
      */
     restoreSpec(input: RestoreSpecInput, actor?: ChangedBy): Promise<RestoreSpecResult>;
+    /**
+     * Build a portable `tar.gz` of release N, deterministically reconstructed
+     * from the versioning tables (`getReleaseSnapshot`) + sanitized `config.json`.
+     * Does NOT read `pagesDir` on disk nor entity HEADs. The returned `tarGzPath`
+     * points at a temp file the CALLER owns (M25 deletes after streaming to
+     * remote); the internal working dir is cleaned up before returning.
+     */
+    buildBundleArchive(releaseId: number): Promise<BuildBundleResult>;
+    /**
+     * CONTRACT-ONLY in v1 — implementation deferred to M26 (Release Import,
+     * `c4s import <bundle>`). The signature is public so the bidirectional bundle
+     * contract is fixed now (write here, read in M26).
+     *
+     * M26 read-direction algorithm (do not implement here):
+     *   1. Parse `manifest.json` FIRST (first tar entry). Missing → throw
+     *      `BUNDLE_MANIFEST_MISSING`. `bundleSchemaVersion` > max supported →
+     *      throw `BUNDLE_SCHEMA_UNSUPPORTED { foundVersion, maxSupportedVersion }`.
+     *   2. Optionally verify SHA-256 (caller supplies expected hash, e.g. from an
+     *      M25 push header). Mismatch → throw `BUNDLE_HASH_MISMATCH { expected, actual }`.
+     *   3. Read `config.json` via a `bundleSchemaVersion`-aware parser; unknown
+     *      fields → warn + ignore (forward-compat).
+     *   4. Stream `pages/<path>.md`; reject `..` / absolute / null-byte paths →
+     *      throw `BUNDLE_MALFORMED_ENTRY { path, reason }`.
+     *   5. Stream `entities/<typePlural>.json`; plural absent from local
+     *      `config.entities` → throw `BUNDLE_UNKNOWN_ENTITY_TYPE { type }`.
+     *   6. Compose a `SpecSnapshot` (same shape as `getReleaseSnapshot`). M26 owns
+     *      what to do with it (UPSERT restore / dry-run diff / read-only mount).
+     * All errors are structured (code + payload), never bare strings.
+     */
+    restoreBundleArchive(_stream: NodeJS.ReadableStream): Promise<SpecSnapshot>;
     private findReleaseRow;
     private toRelease;
     private computeCountBreakdown;

package/dist/server/services/release.js

@@ -9,6 +9,8 @@
  */
 import { DomainError } from './tags.js';
 import { HostEntityWriter } from './entity-writer.js';
+import { readConfig } from '../config.js';
+import { buildBundleArchive as buildBundleArchiveImpl, } from './release-bundle.js';
 const ENTITY_TYPES = ['endpoint', 'dto', 'database-table', 'ui-view', 'ac'];
 const ENTITY_TABLES = {
     endpoint: 'endpoint',
@@ -27,7 +29,8 @@ export class ReleaseService {
     tagsService;
     pagesService;
     watcher;
-    constructor(db, host, versions, pageVersions, pageSerializer, rawReader, tagsService, pagesService, watcher = null) {
+    cwd;
+    constructor(db, host, versions, pageVersions, pageSerializer, rawReader, tagsService, pagesService, watcher = null, cwd = process.cwd()) {
         this.db = db;
         this.host = host;
         this.versions = versions;
@@ -37,6 +40,7 @@ export class ReleaseService {
         this.tagsService = tagsService;
         this.pagesService = pagesService;
         this.watcher = watcher;
+        this.cwd = cwd;
     }
     // ─── Listing & retrieval ─────────────────────────────────────────────────
     listReleases() {
@@ -52,6 +56,17 @@ export class ReleaseService {
         const release = this.toRelease(row);
         return { ...release, countBreakdown: this.computeCountBreakdown(row.id) };
     }
+    /**
+     * Count of captures still queued at HEAD — entity_version + page_version rows
+     * with `release_id IS NULL`. Drives the M25 "You have N unreleased changes"
+     * banner shown only on the latest (mutable) release card.
+     */
+    countUnreleased() {
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS n FROM entity_version WHERE release_id IS NULL`)
+            .get();
+        return row.n + this.pageVersions.countUnreleased();
+    }
     // ─── Mutations ───────────────────────────────────────────────────────────
     /**
      * Manual release creation (decyzja 9: zero auto-trigger). Validates
@@ -457,6 +472,43 @@ export class ReleaseService {
         }
         return { releaseId, entityResults, pageResults };
     }
+    // ─── Portable bundle (transport format — M25 push / M26 import) ────────────
+    /**
+     * Build a portable `tar.gz` of release N, deterministically reconstructed
+     * from the versioning tables (`getReleaseSnapshot`) + sanitized `config.json`.
+     * Does NOT read `pagesDir` on disk nor entity HEADs. The returned `tarGzPath`
+     * points at a temp file the CALLER owns (M25 deletes after streaming to
+     * remote); the internal working dir is cleaned up before returning.
+     */
+    async buildBundleArchive(releaseId) {
+        const snapshot = this.getReleaseSnapshot(releaseId); // throws NOT_FOUND if missing
+        const release = this.getRelease(releaseId);
+        return buildBundleArchiveImpl(snapshot, release, readConfig(this.cwd));
+    }
+    /**
+     * CONTRACT-ONLY in v1 — implementation deferred to M26 (Release Import,
+     * `c4s import <bundle>`). The signature is public so the bidirectional bundle
+     * contract is fixed now (write here, read in M26).
+     *
+     * M26 read-direction algorithm (do not implement here):
+     *   1. Parse `manifest.json` FIRST (first tar entry). Missing → throw
+     *      `BUNDLE_MANIFEST_MISSING`. `bundleSchemaVersion` > max supported →
+     *      throw `BUNDLE_SCHEMA_UNSUPPORTED { foundVersion, maxSupportedVersion }`.
+     *   2. Optionally verify SHA-256 (caller supplies expected hash, e.g. from an
+     *      M25 push header). Mismatch → throw `BUNDLE_HASH_MISMATCH { expected, actual }`.
+     *   3. Read `config.json` via a `bundleSchemaVersion`-aware parser; unknown
+     *      fields → warn + ignore (forward-compat).
+     *   4. Stream `pages/<path>.md`; reject `..` / absolute / null-byte paths →
+     *      throw `BUNDLE_MALFORMED_ENTRY { path, reason }`.
+     *   5. Stream `entities/<typePlural>.json`; plural absent from local
+     *      `config.entities` → throw `BUNDLE_UNKNOWN_ENTITY_TYPE { type }`.
+     *   6. Compose a `SpecSnapshot` (same shape as `getReleaseSnapshot`). M26 owns
+     *      what to do with it (UPSERT restore / dry-run diff / read-only mount).
+     * All errors are structured (code + payload), never bare strings.
+     */
+    async restoreBundleArchive(_stream) {
+        throw new Error('NOT_IMPLEMENTED — restoreBundleArchive deferred to M26 (Release Import)');
+    }
     // ─── Internals ───────────────────────────────────────────────────────────
     findReleaseRow(idOrName) {
         if (typeof idOrName === 'number') {