@wjarka/cezarion 0.10.0-pr30.54

package/dist/planner.js

@@ -0,0 +1,268 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { createRunner } from './core/runner-factory.js';
+import { loadConfig } from './config.js';
+import { discoverSkills } from './skills.js';
+import { resolveProfileEnvForRoot } from './workspace/agent-profiles.js';
+import { workflowStepSchema } from './workflows/types.js';
+/**
+ * Chain-from-prompt (spec 008): one cheap `claude` call turns the user's task
+ * into a proposed chain of workflow steps built from the skills at hand plus a
+ * detected verification command. The planner NEVER blocks the user — any
+ * error, timeout or unparseable answer degrades to a one-step quick-task plan
+ * with `fallback: true` so the GUI can show a dim note.
+ */
+const PLANNER_TIMEOUT_MS = 60_000;
+const PLANNER_SYSTEM_PROMPT = 'You are a planning assistant for an AI coding agent cockpit. Respond with ONLY a JSON object: ' +
+    '{"title":string,"steps":[{"skill"?:string,"name":string,"prompt"?:string,"command"?:string}],"rationale":string}. ' +
+    'Rules: pick skills ONLY from the provided catalog; a step has either "prompt" (an agent step) or ' +
+    '"command" (a shell verification check); include the {{task}} placeholder in agent prompts where ' +
+    "the user's task text belongs; 1-5 steps; prefer fewer; \"title\" is a short kebab-case name for " +
+    'the whole workflow (2-4 words, e.g. "fix-and-review").';
+const plannerResponseSchema = z.object({
+    /** A short workflow name the builder pre-fills. Optional so older / partial answers still parse. */
+    title: z.string().optional(),
+    steps: z
+        .array(z.object({
+        skill: z.string().optional(),
+        name: z.string().min(1),
+        prompt: z.string().optional(),
+        command: z.string().optional(),
+    }))
+        .min(1)
+        .max(5),
+    rationale: z.string().default(''),
+});
+export async function planChain(repoRoot, task) {
+    const [skills, config, verifyCommands] = await Promise.all([
+        discoverSkills(repoRoot),
+        loadConfig(repoRoot),
+        detectVerifyCommands(repoRoot),
+    ]);
+    const skillNames = new Set(skills.map((s) => s.name));
+    const userPrompt = buildPlannerPrompt(task, skills, verifyCommands);
+    // Plan with the configured default runner. `plannerModel` ("sonnet") is a
+    // Claude alias, so only pass it when the planner runs on Claude — Codex /
+    // OpenCode pick their own default model instead.
+    const runner = createRunner(config.defaultRunner);
+    const plannerModel = config.defaultRunner === 'claude' ? config.plannerModel : undefined;
+    // Plan under the SAME agent account this project's tasks run on (spec
+    // 2026-07-29-agent-profiles). Without this the planner would quietly bill the personal
+    // subscription for a project the user pointed at their work account.
+    const { env: profileEnv } = await resolveProfileEnvForRoot(repoRoot, config.defaultRunner);
+    // One retry on an unparseable answer; a runner error goes straight to fallback.
+    for (let attempt = 0; attempt < 2; attempt++) {
+        let text;
+        try {
+            const result = await runner.run({
+                systemPrompt: PLANNER_SYSTEM_PROMPT,
+                userPrompt,
+                cwd: repoRoot,
+                allowedTools: [],
+                ...(Object.keys(profileEnv).length > 0 ? { env: profileEnv } : {}),
+                model: plannerModel,
+                timeoutMs: PLANNER_TIMEOUT_MS,
+            });
+            text = result.text;
+        }
+        catch {
+            break;
+        }
+        const parsed = parseStructured(text, plannerResponseSchema);
+        if (!parsed)
+            continue;
+        const steps = sanitizeSteps(parsed.steps, skillNames);
+        if (steps.length === 0)
+            break; // everything got rejected — degrade
+        const name = proposeWorkflowName(parsed.title);
+        return { ...(name ? { name } : {}), steps, rationale: parsed.rationale, fallback: false };
+    }
+    return {
+        steps: [{ id: 'task', name: 'Do the task', prompt: '{{task}}' }],
+        rationale: 'planner unavailable — single-step plan',
+        fallback: true,
+    };
+}
+/** The `[cez-planner]` marker lets the CEZ_DRY_RUN mock recognize a planning call. */
+function buildPlannerPrompt(task, skills, verifyCommands) {
+    const catalog = skills.length
+        ? skills.map((s) => `- ${s.name} — ${s.description ?? ''}`).join('\n')
+        : '(no skills available)';
+    const verify = verifyCommands.length
+        ? verifyCommands.map((c) => `- ${c}`).join('\n')
+        : '(none detected)';
+    return [
+        '[cez-planner] Plan a chain of steps for this task.',
+        '',
+        'Task:',
+        task,
+        '',
+        'Skill catalog (name — description):',
+        catalog,
+        '',
+        'Verification commands detected in this repo:',
+        verify,
+    ].join('\n');
+}
+/**
+ * Detect verification commands the planner may propose as `check` steps:
+ * `package.json` scripts (test/lint/build) and Makefile targets (first 50
+ * lines). Best effort — an unreadable file just contributes nothing.
+ */
+async function detectVerifyCommands(repoRoot) {
+    const out = [];
+    const pkgSchema = z.object({ scripts: z.record(z.string(), z.string()).default({}) });
+    try {
+        const raw = JSON.parse(await readFile(join(repoRoot, 'package.json'), 'utf8'));
+        const pkg = pkgSchema.safeParse(raw);
+        if (pkg.success) {
+            if (pkg.data.scripts['test'])
+                out.push('npm test');
+            if (pkg.data.scripts['lint'])
+                out.push('npm run lint');
+            if (pkg.data.scripts['build'])
+                out.push('npm run build');
+        }
+    }
+    catch {
+        // no package.json — fine
+    }
+    try {
+        const make = await readFile(join(repoRoot, 'Makefile'), 'utf8');
+        for (const line of make.split('\n').slice(0, 50)) {
+            const m = /^([A-Za-z0-9_.-]+):(?!=)/.exec(line);
+            if (m && m[1] && !m[1].startsWith('.'))
+                out.push(`make ${m[1]}`);
+            if (out.length >= 8)
+                break;
+        }
+    }
+    catch {
+        // no Makefile — fine
+    }
+    return out;
+}
+/**
+ * Turn the model's raw steps into valid `WorkflowStepDef`s: exactly one of
+ * prompt/command, unknown skills stripped (the prompt still carries the step),
+ * ids derived from names with `-2`-style dedup. Steps that can't be repaired
+ * are dropped — the caller falls back when nothing survives.
+ */
+function sanitizeSteps(raw, skillNames) {
+    const out = [];
+    const usedIds = new Set();
+    for (const s of raw) {
+        let skill = s.skill?.trim() || undefined;
+        const prompt = s.prompt?.trim() || undefined;
+        const command = s.command?.trim() || undefined;
+        if (Boolean(prompt) === Boolean(command))
+            continue; // needs exactly one
+        if (command)
+            skill = undefined; // a shell check carries no skill
+        if (skill && !skillNames.has(skill))
+            skill = undefined; // unknown skill → plain prompt
+        const id = uniqueId(slugify(s.name) || 'step', usedIds);
+        const candidate = workflowStepSchema.safeParse({
+            id,
+            name: s.name,
+            ...(skill ? { skill } : {}),
+            ...(prompt ? { prompt } : {}),
+            ...(command ? { command } : {}),
+        });
+        if (!candidate.success)
+            continue;
+        usedIds.add(id);
+        out.push(candidate.data);
+    }
+    return out;
+}
+export function slugify(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * The proposed workflow title, normalized to the same kebab-case slug the builder saves as a
+ * file name — so what the auto chain creator pre-fills is already a valid workflow name. A blank
+ * or slug-less title (e.g. all punctuation) answers undefined, and the caller keeps the current
+ * name instead of blanking it.
+ */
+export function proposeWorkflowName(raw) {
+    const slug = slugify((raw ?? '').trim());
+    return slug || undefined;
+}
+function uniqueId(base, used) {
+    if (!used.has(base))
+        return base;
+    for (let n = 2;; n++) {
+        const id = `${base}-${n}`;
+        if (!used.has(id))
+            return id;
+    }
+}
+/**
+ * Best-effort structured-output extraction (trimmed from @cezar/core's
+ * `parseStructured`): try the whole string after stripping a ```json fence,
+ * then scan for balanced top-level `{...}` blocks and return the first that
+ * validates. Null when nothing does — the caller decides how to recover.
+ */
+export function parseStructured(raw, schema) {
+    const cleaned = raw
+        .replace(/^```(?:json|javascript|js|jsonl)?\s*\n?/im, '')
+        .replace(/\n?```\s*$/m, '')
+        .trim();
+    try {
+        return schema.parse(JSON.parse(cleaned));
+    }
+    catch {
+        for (const candidate of extractJsonObjectCandidates(raw)) {
+            try {
+                return schema.parse(JSON.parse(candidate));
+            }
+            catch {
+                continue;
+            }
+        }
+        return null;
+    }
+}
+function extractJsonObjectCandidates(raw) {
+    const candidates = [];
+    let start = -1;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < raw.length; i++) {
+        const ch = raw[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === '\\')
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+        }
+        else if (ch === '{') {
+            if (depth === 0)
+                start = i;
+            depth++;
+        }
+        else if (ch === '}') {
+            if (depth === 0)
+                continue;
+            depth--;
+            if (depth === 0 && start >= 0) {
+                candidates.push(raw.slice(start, i + 1));
+                start = -1;
+            }
+        }
+    }
+    return candidates;
+}
+//# sourceMappingURL=planner.js.map

package/dist/planner.js.map

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

package/dist/release/manifests.d.ts

@@ -0,0 +1,81 @@
+/** 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.
+ *
+ *  Deliberately name-agnostic: names come from the checked-out manifests at call time, never
+ *  from constants, so a package rename lands without touching this pipeline.
+ */
+/** 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;
+/**
+ * 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.
+ */
+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 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.
+ *
+ * Two pins, both derived from the manifests rather than hardcoded:
+ *   - the alias → the service, so `npx <alias>@<v>` runs the matching CLI;
+ *   - the service → the api-client, so a published service can never resolve a client build it
+ *     was not released with.
+ *
+ * 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,74 @@
+/** 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.
+ *
+ *  Deliberately name-agnostic: names come from the checked-out manifests at call time, never
+ *  from constants, so a package rename lands without touching this pipeline.
+ */
+/**
+ * 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;
+}
+/**
+ * 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.
+ *
+ * Two pins, both derived from the manifests rather than hardcoded:
+ *   - the alias → the service, so `npx <alias>@<v>` runs the matching CLI;
+ *   - the service → the api-client, so a published service can never resolve a client build it
+ *     was not released with.
+ *
+ * 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, alias } = manifests;
+    const range = pin(version);
+    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),
+        alias: {
+            ...pinDependency({ ...alias, ...inherited, version }, cezar.name, 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, [cezar.name]: 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;AAaH;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,GAAiB;IAC7C,OAAO,GAAG,CAAC,OAAO,KAAK,IAAI,CAAC;AAC9B,CAAC;AAgCD;;;;;;;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;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAA2B,EAC3B,OAAe,EACf,GAAa;IAEb,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC;IACxD,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;IAE3B,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,KAAK,EAAE;YACL,GAAG,aAAa,CAAC,EAAE,GAAG,KAAK,EAAE,GAAG,SAAS,EAAE,OAAO,EAAE,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC;YACxE,sFAAsF;YACtF,kFAAkF;YAClF,YAAY,EAAE,EAAE,GAAG,KAAK,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE;SAC7D;KACF,CAAC;AACJ,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` and `push` publish previews; `schedule`
+     *  and `workflow_dispatch` publish only the explicitly requested nightly. */
+    eventName: string;
+    /** `GITHUB_REF_NAME` for push events — only `develop` publishes a snapshot;
+     *  `main` is reserved for owner-driven stable releases (see stable.ts) and for
+     *  the nightly channel below, which 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;
+    /** `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;
+    /** PR number for pull_request events; absent/invalid → no publish. */
+    prNumber?: number;
+    /** `owner/name` of the PR head repo — fork PRs (≠ `repo`) never publish. */
+    headRepo?: string;
+    /** `GITHUB_REPOSITORY` — this repo's `owner/name`. */
+    repo?: string;
+    /** 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;
+}
+/** 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') {
+        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 `develop` publishes a snapshot. `main` is deliberately excluded so a
+        // merge to main never touches npm — stable `latest` releases are cut
+        // manually via the Release workflow (stable.ts). Defense in depth: the
+        // workflow's `if` already restricts the push channel to develop.
+        if (ctx.refName === 'develop')
+            return { channel: 'develop', distTag: 'develop' };
+        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;