@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5685

package/dist/release/compatibility.js

@@ -0,0 +1,62 @@
+import { cpSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { productIdentity } from '../home/identity.js';
+/** Shared shim bytes for packing and trusted archive validation. */
+export function compatibilityEntry() {
+    return `#!/usr/bin/env node\nimport ${JSON.stringify(productIdentity(true).npmPackage)};\n`;
+}
+/** Every recorded entry survives promotion, including the original single-bin alias. */
+export const COMPATIBILITY_ENTRIES = ['dist/index.js', 'dist/hsq.js', 'dist/cez.js', 'dist/cezarion.js',
+    'bin.js', 'cezarion.js', 'cez.js', 'hsq.js'];
+/** Matching old-name releases retain deterministic updates during the deprecation window. */
+export function compatibilityManifests(runtime, rebrand = productIdentity().rebrand) {
+    if (!rebrand || runtime.private === true)
+        return {};
+    const old = productIdentity(false), active = productIdentity(true);
+    const shared = {
+        version: runtime.version, type: 'module', license: runtime.license,
+        repository: runtime.repository, homepage: runtime.homepage, bugs: runtime.bugs,
+        engines: runtime.engines, gitHead: runtime.gitHead,
+        dependencies: { [active.npmPackage]: runtime.version },
+        bin: { cezarion: 'dist/index.js', cez: 'dist/index.js', hsq: 'dist/hsq.js' },
+        exports: { '.': './dist/index.js', './app-type': './dist/server/app-type.js', './package.json': './package.json' },
+        files: ['dist', 'web/dist', 'bin.js', 'cezarion.js', 'cez.js', 'hsq.js'],
+    };
+    return {
+        legacyScoped: { ...shared, name: old.npmPackage },
+        // Shipped alias updaters validate the old scoped dependency. Keep the direct
+        // runtime edge too, so the new updater retains its canonical runtime paths.
+        legacyAlias: { ...shared, name: old.npmAlias,
+            dependencies: { [active.npmPackage]: runtime.version, [old.npmPackage]: runtime.version } },
+    };
+}
+/** Disposable pack trees only. The dispatcher owns the notice; these imports add none. */
+export function withCompatibilityPackages(source, runtime, action, rebrand = productIdentity().rebrand) {
+    const manifests = compatibilityManifests(runtime, rebrand);
+    if (!Object.keys(manifests).length)
+        return action({});
+    const root = mkdtempSync(join(tmpdir(), 'release-compatibility-'));
+    try {
+        const packages = Object.fromEntries(Object.entries(manifests).map(([key, manifest]) => {
+            const dir = join(root, key);
+            mkdirSync(join(dir, 'dist'), { recursive: true });
+            // Both old scoped validators and managed installs require the real built cockpit.
+            cpSync(join(source, 'web/dist'), join(dir, 'web/dist'), { recursive: true });
+            for (const entry of COMPATIBILITY_ENTRIES) {
+                writeFileSync(join(dir, entry), compatibilityEntry(), { mode: 0o755 });
+            }
+            mkdirSync(join(dir, 'dist/server'), { recursive: true });
+            const appType = `${JSON.stringify(`${productIdentity(true).npmPackage}/app-type`)};\n`;
+            writeFileSync(join(dir, 'dist/server/app-type.js'), `export * from ${appType}`);
+            writeFileSync(join(dir, 'dist/server/app-type.d.ts'), `export type * from ${appType}`);
+            writeFileSync(join(dir, 'package.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+            return [key, { dir, manifest }];
+        }));
+        return action(packages);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=compatibility.js.map

package/dist/release/compatibility.js.map

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

package/dist/release/manifests.d.ts

@@ -0,0 +1,112 @@
+/** The manifest arithmetic both release channels share — the pure half of stamping.
+ *
+ *  `stable.ts` and `snapshot.ts` differ in exactly one decision (how a released package pins
+ *  its sibling: a caret range for stable, an exact pin for a snapshot), so everything else
+ *  lives here rather than twice.
+ *
+ *  Source stamping retains workspace names from checked-out manifests. Publication projects
+ *  the active service name from productIdentity without renaming source workspaces.
+ */
+/** The minimal manifest shape the stamper touches; everything else passes through. */
+export interface ManifestLike {
+    name: string;
+    version: string;
+    /** npm's own opt-out. A private package is still versioned in lockstep, never published. */
+    private?: boolean;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    [key: string]: unknown;
+}
+/**
+ * Whether a release stamps AND publishes this package, or only stamps it.
+ *
+ * The distinction exists because "in the release" and "on the registry" are different things.
+ * A package that ships nowhere yet still needs its version moved in lockstep: the api-client is
+ * the worked example — the service pins it, so a frozen version would leave that range pointing
+ * at a build the release was not cut from, which is exactly the drift this pipeline exists to
+ * prevent. Publishing is gated on npm's own `private` flag rather than a list here, so opening
+ * a package up is one line in ITS manifest and no change to the release code.
+ */
+export declare function isPublishable(pkg: ManifestLike): boolean;
+/**
+ * Relative dirs of every manifest a release stamps, keyed as `ReleaseManifests`.
+ *
+ * The completeness test walks the workspace root's `workspaces` array against these values, so a
+ * new workspace that is not listed here fails CI rather than shipping a bump `npm ci` cannot
+ * install. `alias` is not a workspace (it lives next to `packages/`) and is the one extra entry.
+ */
+export declare function releaseManifestDirs(rebrand?: boolean): {
+    readonly contract: 'packages/contract';
+    readonly apiClient: 'packages/api-client';
+    readonly cezar: 'packages/cezar';
+    readonly web: 'packages/web';
+    readonly alias: "alias-cezarion" | "alias-hsq";
+};
+export declare const RELEASE_MANIFEST_DIRS: {
+    readonly contract: 'packages/contract';
+    readonly apiClient: 'packages/api-client';
+    readonly cezar: 'packages/cezar';
+    readonly web: 'packages/web';
+    readonly alias: "alias-cezarion" | "alias-hsq";
+};
+/** Source workspaces keep their names so builds and version-only bump PRs still work. */
+export declare function publicationManifests(manifests: ReleaseManifests, rebrand?: boolean): ReleaseManifests;
+/**
+ * Every manifest a release stamps.
+ *
+ * The order of the fields is the order they must be PUBLISHED in, because each one depends on
+ * the one before it: the alias is a bin-shim over the service, and the service (from the phase
+ * where it stops merely testing against the client and starts importing it) depends on the
+ * api-client. Publishing the dependent first would briefly advertise a version of its
+ * dependency that does not exist on the registry yet. Private members of the set are still
+ * stamped — they are simply skipped at publish time.
+ */
+export interface ReleaseManifests {
+    /**
+     * The API contract (zod schemas + inferred types). FIRST in the stamped set because both the
+     * api-client and the service depend on it, so its version has to settle before their pins are
+     * rewritten. Like the api-client it is `private`, so it is stamped but never published — which
+     * is exactly why the service cannot simply depend on it at runtime: `packages/cezar/scripts/
+     * inline-contract.mjs` folds it into `dist/contract/` at build time instead. It moves to a real
+     * publish the day that script is deleted.
+     */
+    contract: ManifestLike;
+    /** The contract package a consumer installs to talk to a cezar service. */
+    apiClient: ManifestLike;
+    /** The published service + CLI. */
+    cezar: ManifestLike;
+    /**
+     * The cockpit SPA. `private`, so never published, but it consumes the api-client and the
+     * service, and a bump that leaves its ranges on the previous version makes `npm ci` on the
+     * version-bump branch fail the same way an unstamped contract does.
+     */
+    web: ManifestLike;
+    /** The unscoped bin alias, so `npx cezarion` works. */
+    alias: ManifestLike;
+}
+/** How a released package pins a sibling it depends on. */
+export type PinStyle = (version: string) => string;
+/**
+ * Rewrite `pkg`'s range for `depName`, in whichever dependency section already declares it.
+ *
+ * Absent means absent: a package that does not depend on the other is returned untouched. That
+ * is what lets the api-client dependency migrate from `devDependencies` (today: only the tests
+ * import it) to `dependencies` (once the service imports its DTOs at runtime) without the
+ * release pipeline needing to know it happened.
+ */
+export declare function pinDependency(pkg: ManifestLike, depName: string, range: string): ManifestLike;
+/**
+ * Stamp every manifest to `version` and re-pin the intra-release dependencies.
+ *
+ * Pins, all derived from the manifests rather than hardcoded:
+ *   - the alias → the service, so `npx <alias>@<v>` runs the matching CLI;
+ *   - the service → the api-client (and the contract), so a published service can never resolve
+ *     a client build it was not released with;
+ *   - the cockpit → the api-client and the service, so a bump branch stays `npm ci`-able.
+ *
+ * The alias also inherits `repository`/`homepage`/`bugs` from the service manifest: we publish
+ * with `--provenance`, and npm rejects (E422) any manifest whose `repository.url` does not
+ * match the building repo. The alias file carries none of its own, so it borrows the
+ * service's — already correct, and being a git URL, unaffected by any npm-name rename.
+ */
+export declare function stampManifestSet(manifests: ReleaseManifests, version: string, pin: PinStyle): ReleaseManifests;

package/dist/release/manifests.js

@@ -0,0 +1,104 @@
+/** The manifest arithmetic both release channels share — the pure half of stamping.
+ *
+ *  `stable.ts` and `snapshot.ts` differ in exactly one decision (how a released package pins
+ *  its sibling: a caret range for stable, an exact pin for a snapshot), so everything else
+ *  lives here rather than twice.
+ *
+ *  Source stamping retains workspace names from checked-out manifests. Publication projects
+ *  the active service name from productIdentity without renaming source workspaces.
+ */
+import { productIdentity } from '../home/identity.js';
+import { REBRAND_SWITCH } from '../home/switch.js';
+/**
+ * Whether a release stamps AND publishes this package, or only stamps it.
+ *
+ * The distinction exists because "in the release" and "on the registry" are different things.
+ * A package that ships nowhere yet still needs its version moved in lockstep: the api-client is
+ * the worked example — the service pins it, so a frozen version would leave that range pointing
+ * at a build the release was not cut from, which is exactly the drift this pipeline exists to
+ * prevent. Publishing is gated on npm's own `private` flag rather than a list here, so opening
+ * a package up is one line in ITS manifest and no change to the release code.
+ */
+export function isPublishable(pkg) {
+    return pkg.private !== true;
+}
+/**
+ * Relative dirs of every manifest a release stamps, keyed as `ReleaseManifests`.
+ *
+ * The completeness test walks the workspace root's `workspaces` array against these values, so a
+ * new workspace that is not listed here fails CI rather than shipping a bump `npm ci` cannot
+ * install. `alias` is not a workspace (it lives next to `packages/`) and is the one extra entry.
+ */
+export function releaseManifestDirs(rebrand = REBRAND_SWITCH) {
+    return {
+        contract: 'packages/contract',
+        apiClient: 'packages/api-client',
+        cezar: 'packages/cezar',
+        web: 'packages/web',
+        alias: productIdentity(rebrand).npmAliasDirectory,
+    };
+}
+export const RELEASE_MANIFEST_DIRS = releaseManifestDirs();
+/** Source workspaces keep their names so builds and version-only bump PRs still work. */
+export function publicationManifests(manifests, rebrand = REBRAND_SWITCH) {
+    if (!rebrand)
+        return manifests;
+    return { ...manifests, cezar: { ...manifests.cezar, name: productIdentity(rebrand).npmPackage } };
+}
+/**
+ * Rewrite `pkg`'s range for `depName`, in whichever dependency section already declares it.
+ *
+ * Absent means absent: a package that does not depend on the other is returned untouched. That
+ * is what lets the api-client dependency migrate from `devDependencies` (today: only the tests
+ * import it) to `dependencies` (once the service imports its DTOs at runtime) without the
+ * release pipeline needing to know it happened.
+ */
+export function pinDependency(pkg, depName, range) {
+    const sections = ['dependencies', 'devDependencies', 'peerDependencies'];
+    const out = { ...pkg };
+    for (const section of sections) {
+        const deps = pkg[section];
+        if (deps && depName in deps)
+            out[section] = { ...deps, [depName]: range };
+    }
+    return out;
+}
+/**
+ * Stamp every manifest to `version` and re-pin the intra-release dependencies.
+ *
+ * Pins, all derived from the manifests rather than hardcoded:
+ *   - the alias → the service, so `npx <alias>@<v>` runs the matching CLI;
+ *   - the service → the api-client (and the contract), so a published service can never resolve
+ *     a client build it was not released with;
+ *   - the cockpit → the api-client and the service, so a bump branch stays `npm ci`-able.
+ *
+ * The alias also inherits `repository`/`homepage`/`bugs` from the service manifest: we publish
+ * with `--provenance`, and npm rejects (E422) any manifest whose `repository.url` does not
+ * match the building repo. The alias file carries none of its own, so it borrows the
+ * service's — already correct, and being a git URL, unaffected by any npm-name rename.
+ */
+export function stampManifestSet(manifests, version, pin) {
+    const { contract, apiClient, cezar, web, alias } = manifests;
+    const range = pin(version);
+    // The new alias depends on the published identity; workspace consumers retain the source name.
+    const aliasTarget = alias.name === productIdentity(true).npmAlias
+        ? productIdentity(true).npmPackage : cezar.name;
+    const inherited = {};
+    for (const field of ['repository', 'homepage', 'bugs']) {
+        if (cezar[field] !== undefined)
+            inherited[field] = cezar[field];
+    }
+    return {
+        contract: { ...contract, version },
+        apiClient: pinDependency({ ...apiClient, version }, contract.name, range),
+        cezar: pinDependency(pinDependency({ ...cezar, version }, apiClient.name, range), contract.name, range),
+        web: pinDependency(pinDependency({ ...web, version }, apiClient.name, range), cezar.name, range),
+        alias: {
+            ...pinDependency({ ...alias, ...inherited, version }, aliasTarget, range),
+            // The alias exists only to depend on the service — an unpinned or missing entry would
+            // make `npx <alias>` install nothing useful, so this one is asserted, not merged.
+            dependencies: { ...alias.dependencies, [aliasTarget]: range },
+        },
+    };
+}
+//# sourceMappingURL=manifests.js.map

package/dist/release/manifests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifests.js","sourceRoot":"","sources":["../../src/release/manifests.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAanD;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,GAAiB;IAC7C,OAAO,GAAG,CAAC,OAAO,KAAK,IAAI,CAAC;AAC9B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAO,GAAG,cAAc;IAC1D,OAAO;QACL,QAAQ,EAAE,mBAAmB;QAC7B,SAAS,EAAE,qBAAqB;QAChC,KAAK,EAAE,gBAAgB;QACvB,GAAG,EAAE,cAAc;QACnB,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC,iBAAiB;KACzC,CAAC;AACb,CAAC;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAG,mBAAmB,EAAE,CAAC;AAE3D,yFAAyF;AACzF,MAAM,UAAU,oBAAoB,CAAC,SAA2B,EAAE,OAAO,GAAG,cAAc;IACxF,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,OAAO,EAAE,GAAG,SAAS,EAAE,KAAK,EAAE,EAAE,GAAG,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC;AACpG,CAAC;AAuCD;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,GAAiB,EAAE,OAAe,EAAE,KAAa;IAC7E,MAAM,QAAQ,GAAG,CAAC,cAAc,EAAE,iBAAiB,EAAE,kBAAkB,CAAU,CAAC;IAClF,MAAM,GAAG,GAAiB,EAAE,GAAG,GAAG,EAAE,CAAC;IACrC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAuC,CAAC;QAChE,IAAI,IAAI,IAAI,OAAO,IAAI,IAAI;YAAE,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC;IAC5E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAA2B,EAC3B,OAAe,EACf,GAAa;IAEb,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC;IAC7D,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,+FAA+F;IAC/F,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC,IAAI,CAAC,CAAC,QAAQ;QAC/D,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;IAElD,MAAM,SAAS,GAA0B,EAAE,CAAC;IAC5C,KAAK,MAAM,KAAK,IAAI,CAAC,YAAY,EAAE,UAAU,EAAE,MAAM,CAAU,EAAE,CAAC;QAChE,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,SAAS;YAAE,SAAS,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IAClE,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,EAAE,GAAG,QAAQ,EAAE,OAAO,EAAE;QAClC,SAAS,EAAE,aAAa,CAAC,EAAE,GAAG,SAAS,EAAE,OAAO,EAAE,EAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;QACzE,KAAK,EAAE,aAAa,CAClB,aAAa,CAAC,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,EAAE,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,EAC3D,QAAQ,CAAC,IAAI,EACb,KAAK,CACN;QACD,GAAG,EAAE,aAAa,CAChB,aAAa,CAAC,EAAE,GAAG,GAAG,EAAE,OAAO,EAAE,EAAE,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,EACzD,KAAK,CAAC,IAAI,EACV,KAAK,CACN;QACD,KAAK,EAAE;YACL,GAAG,aAAa,CAAC,EAAE,GAAG,KAAK,EAAE,GAAG,SAAS,EAAE,OAAO,EAAE,EAAE,WAAW,EAAE,KAAK,CAAC;YACzE,sFAAsF;YACtF,kFAAkF;YAClF,YAAY,EAAE,EAAE,GAAG,KAAK,CAAC,YAAY,EAAE,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE;SAC9D;KACF,CAAC;AACJ,CAAC"}

package/dist/release/publication.d.ts

@@ -0,0 +1,3 @@
+import type { ManifestLike } from './manifests.ts';
+/** Publish a renamed manifest from a disposable copy. Never rewrite a source workspace name. */
+export declare function withPublicationPackage<T>(dir: string, manifest: ManifestLike, action: (cwd: string) => T): T;

package/dist/release/publication.js

@@ -0,0 +1,34 @@
+import { cpSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+function sourceManifest(dir, manifest) {
+    if (manifest.gitHead)
+        return manifest;
+    try {
+        // npm normally discovers this from its cwd. The disposable copy is outside Git;
+        // retain the source SHA so stable publish retries can verify the existing version.
+        const gitHead = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+        return { ...manifest, gitHead };
+    }
+    catch {
+        return manifest;
+    } // Local package fixtures need not be in a Git repository.
+}
+/** Publish a renamed manifest from a disposable copy. Never rewrite a source workspace name. */
+export function withPublicationPackage(dir, manifest, action) {
+    const bytes = readFileSync(join(dir, 'package.json'), 'utf8');
+    if (JSON.parse(bytes).name === manifest.name)
+        return action(dir);
+    const root = mkdtempSync(join(tmpdir(), 'release-package-'));
+    const stage = join(root, 'package');
+    try {
+        cpSync(dir, stage, { recursive: true, filter: source => !['node_modules', '.git'].includes(basename(source)) });
+        writeFileSync(join(stage, 'package.json'), `${JSON.stringify(sourceManifest(dir, manifest), null, 2)}\n`);
+        return action(stage);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=publication.js.map

package/dist/release/publication.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publication.js","sourceRoot":"","sources":["../../src/release/publication.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAG3C,SAAS,cAAc,CAAC,GAAW,EAAE,QAAsB;IACzD,IAAI,QAAQ,CAAC,OAAO;QAAE,OAAO,QAAQ,CAAC;IACtC,IAAI,CAAC;QACH,gFAAgF;QAChF,mFAAmF;QACnF,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACrI,OAAO,EAAE,GAAG,QAAQ,EAAE,OAAO,EAAE,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,QAAQ,CAAC;IAAC,CAAC,CAAC,0DAA0D;AACzF,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,sBAAsB,CAAI,GAAW,EAAE,QAAsB,EAAE,MAA0B;IACvG,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC;IAC9D,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;QAChH,aAAa,CAAC,IAAI,CAAC,KAAK,EAAE,cAAc,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QAC1G,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACjD,CAAC;AACH,CAAC"}

package/dist/release/snapshot.d.ts

@@ -0,0 +1,67 @@
+/** Snapshot release decisions — the pure half of `scripts/release-snapshot.mjs`.
+ *
+ *  Spec `.ai/specs/2026-07-18-npm-preview-publish.md` (#482): every green CI run
+ *  publishes an installable preview of the CLI. This module decides *whether* a
+ *  given CI event publishes, under *which* version and dist-tag, and how the two
+ *  manifests (the scoped package and its unscoped alias) are stamped. Kept
+ *  dependency-free and side-effect-free so the decision is unit-testable; the
+ *  script owns file writes, `npm publish`, and the exit code.
+ *
+ *  Deliberately name-agnostic: package names come from the checked-out manifests
+ *  at call time, never from constants — so the `@pat-lewczuk/cezar` →
+ *  `@wjarka/cezarion` rename (#23) lands independently of this pipeline.
+ */
+import { type ReleaseManifests as ReleaseManifestSet } from './manifests.ts';
+/** The CI facts the decision needs, straight from GitHub Actions' env/event. */
+export interface SnapshotContext {
+    /** `GITHUB_EVENT_NAME` — `pull_request` / `pull_request_target` and `push` publish previews; `schedule`
+     *  and `workflow_dispatch` publish only the explicitly requested nightly. */
+    eventName: string;
+    /** `GITHUB_REF_NAME` for push events — only `main` publishes the `dev` snapshot;
+     *  stable `latest` releases stay owner-driven (see stable.ts). The nightly
+     *  channel below also cuts from `main` but never moves `latest` either. */
+    refName: string;
+    /** `CEZ_RELEASE_CHANNEL` — a channel asked for by name rather than derived from
+     *  the event. Only `.github/workflows/nightly.yml` sets it (to `nightly`); every
+     *  other caller leaves it empty and gets the event-derived channel. Opt-in by
+     *  name is what keeps a `workflow_dispatch` of ci.yml from cutting a nightly by
+     *  accident — the event alone is not enough. */
+    requestedChannel?: string | undefined;
+    /** `YYYYMMDD` (UTC) of the day a nightly is cut — the nightly version is named
+     *  after its date. Required for the nightly channel, ignored by every other. */
+    nightlyDate?: string | undefined;
+    /** PR number for pull request events; absent/invalid → no publish. */
+    prNumber?: number | undefined;
+    /** `owner/name` of the PR head repo — fork PRs (≠ `repo`) never publish. */
+    headRepo?: string | undefined;
+    /** `GITHUB_REPOSITORY` — this repo's `owner/name`. */
+    repo?: string | undefined;
+    /** The base version from the root `package.json` (e.g. `0.1.5`). */
+    baseVersion: string;
+    /** `GITHUB_RUN_NUMBER` — monotonic per workflow; makes versions unique. */
+    runNumber: number;
+    /** `GITHUB_RUN_ATTEMPT` — appended only when > 1 so re-runs never collide. */
+    runAttempt?: number | undefined;
+}
+/** A publishable snapshot: prerelease version + the explicit dist-tag.
+ *  The dist-tag is structurally never `latest` — snapshots must not become the
+ *  default install; stable releases stay owner-driven (spec, resolved Q2). */
+export interface SnapshotPlan {
+    channel: string;
+    version: string;
+    distTag: string;
+}
+export declare function computeSnapshot(ctx: SnapshotContext): SnapshotPlan | null;
+export type { ManifestLike, ReleaseManifests } from './manifests.ts';
+/** Stamp the release set to the snapshot version.
+ *
+ *  Every intra-release dependency is pinned **exact** (`0.1.5-pr482.123`, no range) so
+ *  `npx <alias>@<version>` runs exactly the PR's code and the service resolves exactly the
+ *  api-client it was cut with — a `^` range would resolve to whatever newer version exists
+ *  (spec, resolved Q5). Stable releases keep their `^` range and never go through this
+ *  stamper. */
+export declare function stampManifests(manifests: ReleaseManifestSet, version: string): ReleaseManifestSet;
+/** The copy-pasteable commands for the sticky PR comment and the step summary.
+ *  Rendered from the *actual* alias package name so a future rename of the npx
+ *  command can never leave stale instructions (spec, resolved Q1). */
+export declare function buildInstallLines(aliasName: string, version: string): string[];

package/dist/release/snapshot.js

@@ -0,0 +1,97 @@
+/** Snapshot release decisions — the pure half of `scripts/release-snapshot.mjs`.
+ *
+ *  Spec `.ai/specs/2026-07-18-npm-preview-publish.md` (#482): every green CI run
+ *  publishes an installable preview of the CLI. This module decides *whether* a
+ *  given CI event publishes, under *which* version and dist-tag, and how the two
+ *  manifests (the scoped package and its unscoped alias) are stamped. Kept
+ *  dependency-free and side-effect-free so the decision is unit-testable; the
+ *  script owns file writes, `npm publish`, and the exit code.
+ *
+ *  Deliberately name-agnostic: package names come from the checked-out manifests
+ *  at call time, never from constants — so the `@pat-lewczuk/cezar` →
+ *  `@wjarka/cezarion` rename (#23) lands independently of this pipeline.
+ */
+import { stampManifestSet } from './manifests.js';
+export function computeSnapshot(ctx) {
+    const channel = resolveChannel(ctx);
+    if (!channel)
+        return null;
+    if (!ctx.baseVersion || !Number.isInteger(ctx.runNumber) || ctx.runNumber <= 0)
+        return null;
+    const attempt = ctx.runAttempt !== undefined && Number.isInteger(ctx.runAttempt) && ctx.runAttempt > 1
+        ? `.${ctx.runAttempt}`
+        : '';
+    // A nightly is named after the day it was cut — `0.1.5-nightly.20260813.126` —
+    // so `npm view cezarion versions` reads as a calendar and a user can tell at a
+    // glance how old their build is. The run number still trails the date, because a
+    // manual re-cut on the same day must not collide with the scheduled one. Both are
+    // plain numeric semver identifiers, so the ordering stays chronological.
+    const nightly = channel.channel === 'nightly';
+    if (nightly && !/^\d{8}$/.test(ctx.nightlyDate ?? ''))
+        return null;
+    const stamp = nightly ? `${ctx.nightlyDate}.${ctx.runNumber}` : `${ctx.runNumber}`;
+    return {
+        channel: channel.channel,
+        version: `${ctx.baseVersion}-${channel.channel}.${stamp}${attempt}`,
+        distTag: channel.distTag,
+    };
+}
+function resolveChannel(ctx) {
+    // A named channel wins over the event-derived ones, and is the ONLY way to reach
+    // nightly — asked for explicitly by nightly.yml, never inferred from an event.
+    // An unrecognised name publishes nothing rather than silently falling back: a
+    // typo in a workflow should be a no-op, not a publish under the wrong tag.
+    if (ctx.requestedChannel) {
+        if (ctx.requestedChannel !== 'nightly')
+            return null;
+        // Nightly cuts main's tip — on the schedule, or on demand from the Actions tab
+        // when someone needs a fresh build before the next night.
+        if (ctx.eventName !== 'schedule' && ctx.eventName !== 'workflow_dispatch')
+            return null;
+        if (ctx.refName !== 'main')
+            return null;
+        return { channel: 'nightly', distTag: 'nightly' };
+    }
+    if (ctx.eventName === 'pull_request' || ctx.eventName === 'pull_request_target') {
+        const n = ctx.prNumber;
+        if (n === undefined || !Number.isInteger(n) || n <= 0)
+            return null;
+        // Defense in depth: the workflow's `if` already excludes forks, and fork PRs
+        // get no secrets — but the decision must not rely on workflow wiring alone.
+        if (!ctx.headRepo || !ctx.repo || ctx.headRepo !== ctx.repo)
+            return null;
+        return { channel: `pr${n}`, distTag: `pr-${n}` };
+    }
+    if (ctx.eventName === 'push') {
+        // Only `main` publishes the trunk preview (`dev`). Merges never move
+        // `latest` — stable releases are cut manually via the Release workflow
+        // (stable.ts). Defense in depth: the workflow's `if` already restricts
+        // the push channel to main.
+        if (ctx.refName === 'main')
+            return { channel: 'dev', distTag: 'dev' };
+        return null;
+    }
+    return null;
+}
+/** Stamp the release set to the snapshot version.
+ *
+ *  Every intra-release dependency is pinned **exact** (`0.1.5-pr482.123`, no range) so
+ *  `npx <alias>@<version>` runs exactly the PR's code and the service resolves exactly the
+ *  api-client it was cut with — a `^` range would resolve to whatever newer version exists
+ *  (spec, resolved Q5). Stable releases keep their `^` range and never go through this
+ *  stamper. */
+export function stampManifests(manifests, version) {
+    return stampManifestSet(manifests, version, (v) => v);
+}
+/** The copy-pasteable commands for the sticky PR comment and the step summary.
+ *  Rendered from the *actual* alias package name so a future rename of the npx
+ *  command can never leave stale instructions (spec, resolved Q1). */
+export function buildInstallLines(aliasName, version) {
+    const cmd = `npx ${aliasName}@${version}`;
+    return [
+        `${cmd}                                # cockpit at http://localhost:4321`,
+        `${cmd} run "…"                        # headless run`,
+        `${cmd} server-deploy --platform <id>  # roll a server to this exact build`,
+    ];
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/release/snapshot.js.map

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

package/dist/release/stable.d.ts

@@ -0,0 +1,38 @@
+/** Stable-release decisions — the pure half of `scripts/release.mjs`.
+ *
+ *  Sibling of `snapshot.ts`, but for the *owner-driven* `latest` channel. The
+ *  `Release` workflow (`.github/workflows/release.yml`) is run manually and
+ *  never fires from a push, so — unlike snapshots — a stable release is the only
+ *  thing that ever moves the `latest` dist-tag (spec
+ *  `.ai/specs/2026-07-18-npm-preview-publish.md`, #482).
+ *
+ *  Two decisions live here so they stay unit-testable and side-effect-free: the next stable
+ *  version for a given bump, and the pin style the release set is stamped with. Crucially,
+ *  stable releases use a **caret** range — the opposite of the snapshot stamper's exact pin —
+ *  so a stable `cezarion` picks up compatible patch releases of the implementation package.
+ */
+import { type ReleaseManifests as ReleaseManifestSet } from './manifests.ts';
+/** The version-bump modes the Release workflow offers. `existing` publishes the
+ *  version already committed to the service manifest (for hand-prepared releases);
+ *  the rest increment semver from the current base. */
+export type ReleaseBump = 'patch' | 'minor' | 'major' | 'existing';
+export declare const RELEASE_BUMPS: readonly ReleaseBump[];
+export declare function isReleaseBump(value: string): value is ReleaseBump;
+/** Compute the next stable version from the current base and a bump mode.
+ *
+ *  `base` must be a plain `major.minor.patch` (no prerelease/build suffix) — a
+ *  stable release should never start from a snapshot version. `existing` returns
+ *  the base verbatim; the increments zero out the lower components the way
+ *  `npm version` does. Returns `null` for an unparseable base so the caller can
+ *  fail loudly instead of publishing a garbage version. */
+export declare function computeStableVersion(bump: ReleaseBump, base: string): string | null;
+export type { ManifestLike, ReleaseManifests } from './manifests.ts';
+/** Stamp the release set to a stable version.
+ *
+ *  Mirror of `stampSnapshotManifests`, differing in exactly one decision: intra-release
+ *  dependencies get a **caret** range (`^0.1.6`), not an exact pin. A stable `cezarion` should
+ *  follow compatible releases of the implementation package, and a stable service should follow
+ *  compatible releases of the api-client; a snapshot must pin the one exact build it was cut
+ *  from. Everything else — which manifests exist, which sections carry the pin, what the alias
+ *  inherits — lives in `manifests.ts` so the two channels cannot drift apart. */
+export declare function stampStableManifests(manifests: ReleaseManifestSet, version: string): ReleaseManifestSet;

package/dist/release/stable.js

@@ -0,0 +1,55 @@
+/** Stable-release decisions — the pure half of `scripts/release.mjs`.
+ *
+ *  Sibling of `snapshot.ts`, but for the *owner-driven* `latest` channel. The
+ *  `Release` workflow (`.github/workflows/release.yml`) is run manually and
+ *  never fires from a push, so — unlike snapshots — a stable release is the only
+ *  thing that ever moves the `latest` dist-tag (spec
+ *  `.ai/specs/2026-07-18-npm-preview-publish.md`, #482).
+ *
+ *  Two decisions live here so they stay unit-testable and side-effect-free: the next stable
+ *  version for a given bump, and the pin style the release set is stamped with. Crucially,
+ *  stable releases use a **caret** range — the opposite of the snapshot stamper's exact pin —
+ *  so a stable `cezarion` picks up compatible patch releases of the implementation package.
+ */
+import { stampManifestSet } from './manifests.js';
+export const RELEASE_BUMPS = ['patch', 'minor', 'major', 'existing'];
+export function isReleaseBump(value) {
+    return RELEASE_BUMPS.includes(value);
+}
+/** Compute the next stable version from the current base and a bump mode.
+ *
+ *  `base` must be a plain `major.minor.patch` (no prerelease/build suffix) — a
+ *  stable release should never start from a snapshot version. `existing` returns
+ *  the base verbatim; the increments zero out the lower components the way
+ *  `npm version` does. Returns `null` for an unparseable base so the caller can
+ *  fail loudly instead of publishing a garbage version. */
+export function computeStableVersion(bump, base) {
+    const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(base.trim());
+    if (!m)
+        return null;
+    const [major, minor, patch] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    switch (bump) {
+        case 'existing':
+            return `${major}.${minor}.${patch}`;
+        case 'patch':
+            return `${major}.${minor}.${patch + 1}`;
+        case 'minor':
+            return `${major}.${minor + 1}.0`;
+        case 'major':
+            return `${major + 1}.0.0`;
+        default:
+            return null;
+    }
+}
+/** Stamp the release set to a stable version.
+ *
+ *  Mirror of `stampSnapshotManifests`, differing in exactly one decision: intra-release
+ *  dependencies get a **caret** range (`^0.1.6`), not an exact pin. A stable `cezarion` should
+ *  follow compatible releases of the implementation package, and a stable service should follow
+ *  compatible releases of the api-client; a snapshot must pin the one exact build it was cut
+ *  from. Everything else — which manifests exist, which sections carry the pin, what the alias
+ *  inherits — lives in `manifests.ts` so the two channels cannot drift apart. */
+export function stampStableManifests(manifests, version) {
+    return stampManifestSet(manifests, version, (v) => `^${v}`);
+}
+//# sourceMappingURL=stable.js.map

package/dist/release/stable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable.js","sourceRoot":"","sources":["../../src/release/stable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,gBAAgB,EAA+C,MAAM,gBAAgB,CAAC;AAO/F,MAAM,CAAC,MAAM,aAAa,GAA2B,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;AAE7F,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAQ,aAAmC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;2DAM2D;AAC3D,MAAM,UAAU,oBAAoB,CAAC,IAAiB,EAAE,IAAY;IAClE,MAAM,CAAC,GAAG,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACpD,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzE,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,UAAU;YACb,OAAO,GAAG,KAAK,IAAI,KAAK,IAAI,KAAK,EAAE,CAAC;QACtC,KAAK,OAAO;YACV,OAAO,GAAG,KAAK,IAAI,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC1C,KAAK,OAAO;YACV,OAAO,GAAG,KAAK,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC;QACnC,KAAK,OAAO;YACV,OAAO,GAAG,KAAK,GAAG,CAAC,MAAM,CAAC;QAC5B;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAID;;;;;;;iFAOiF;AACjF,MAAM,UAAU,oBAAoB,CAClC,SAA6B,EAC7B,OAAe;IAEf,OAAO,gBAAgB,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC9D,CAAC"}

package/dist/remote-settings-cli.d.ts

@@ -0,0 +1,24 @@
+import type { Home } from './home/home.ts';
+import { type RemoteSettingsState } from './remote-settings.ts';
+/**
+ * `cez remote-settings enable | status | disable` (hearsay-tools/cezarion#2428): the host operator's
+ * grant for editing Agent config and worktree setup from one remote cockpit, named by its listen
+ * port. It runs on the machine that runs Cezarion, as the same user (and the same `CEZ_HOME`) as the
+ * cockpit service. One JSON object per invocation; exit 0 ok, 2 refused, 64 usage.
+ */
+export declare const REMOTE_SETTINGS_WARNING = "Anyone this cockpit admits can now save agent hooks, MCP servers and worktree setup commands that run on this machine as this user. Keep the cockpit behind owner-only Tailscale access or an authenticated HTTPS proxy, bound to loopback.";
+export interface CockpitHealth {
+    url: string;
+    localHandoff: boolean;
+    settingsAdmin?: boolean | undefined;
+}
+export interface RemoteSettingsIo {
+    stdout(line: string): void;
+    /** Running cockpits on this machine; tests replace the loopback port scan. */
+    cockpits?: (env: NodeJS.ProcessEnv) => Promise<CockpitHealth[]>;
+}
+/** `CEZ_URL` when set, otherwise every cockpit answering on the loopback ports. */
+export declare function scanCockpits(env: NodeJS.ProcessEnv): Promise<CockpitHealth[]>;
+/** What one cockpit does with the grants, in one line. */
+export declare function cockpitEffect(cockpit: CockpitHealth, state: RemoteSettingsState): string;
+export declare function runRemoteSettingsCommand(argv: string[], env: NodeJS.ProcessEnv | undefined, io: RemoteSettingsIo | undefined, home: Home): Promise<number>;