@wjarka/cezarion 0.10.0-pr30.54

package/dist/server-install/types.js

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+/**
+ * Contracts for the server installer (spec 2026-07-16-server-installer).
+ * The engine closes over `InstallStep` / `PlatformStrategy` and never learns
+ * what a step *does* — only `check` / `run` / `undo`. That seam is what makes
+ * "use ubuntu as a selector and run it that way" a registry lookup, and what
+ * makes the interactive helpers reusable across every future platform.
+ */
+/** The platforms the registry knows. Extend here + add a strategy file. */
+export const PLATFORM_IDS = ['ubuntu-vps', 'macosx-ngrok'];
+/** Per-step lifecycle. `failed` resumes identically to `pending`. */
+export const STEP_STATUSES = ['pending', 'done', 'skipped', 'failed'];
+/**
+ * One thing a step created, tagged by who owns its removal:
+ *  - `owned`  — cezar authored it and nothing else uses it → uninstall removes it.
+ *  - `shared` — a system tool the operator may now depend on (gh, agent CLIs,
+ *    certbot + its renewal timer, the cert itself) → uninstall lists it with a
+ *    manual removal hint instead of yanking it.
+ */
+export const stepArtifactSchema = z.object({
+    kind: z.enum(['owned', 'shared']),
+    /** file | package | service | cert | htpasswd | config | note */
+    type: z.string().min(1),
+    /** Filesystem path for `owned` files (vhost, unit, htpasswd). */
+    path: z.string().optional(),
+    /** Human name: package id, unit name, cert domain, auth user. */
+    name: z.string().optional(),
+    /** `system` | `user` for services. */
+    scope: z.string().optional(),
+    /** For `shared` artifacts: the exact command the operator can run to remove it. */
+    removeHint: z.string().optional(),
+});
+/** What a step returns from `run()`; `undo()` receives it back verbatim. */
+export const stepCreatedSchema = z
+    .object({ artifacts: z.array(stepArtifactSchema).default([]) })
+    .nullable();
+/**
+ * Persisted per-step outcome — the `steps` map in `server.json`. A status this
+ * version doesn't know (written by a newer cezar) degrades to `failed`, which
+ * keeps the record AND keeps it on uninstall's undo path — never to a parse
+ * failure that would discard the whole ledger.
+ */
+export const stepOutcomeSchema = z.object({
+    status: z.enum(STEP_STATUSES).catch('failed'),
+    created: stepCreatedSchema.optional().catch(null),
+});
+/**
+ * `~/.cezar/server.json` — host-level, install-once. Additive-safe: every new
+ * field is optional / defaulted so an older cezar still parses a newer file
+ * (BACKWARD_COMPATIBILITY cross-version-state rule). No secrets live here.
+ */
+export const serverStateSchema = z
+    .object({
+    schema: z.literal(1).catch(1),
+    /**
+     * Free string, not an enum: a `server.json` written by a newer cezar with a
+     * platform this version doesn't ship must still parse — the registry lookup
+     * is where "unknown platform" is decided, with the ledger intact.
+     */
+    platform: z.string().min(1).optional().catch(undefined),
+    /**
+     * Instance id (slug) this record belongs to — `default` for the original
+     * single-cockpit host, or a domain-derived slug for a named instance under
+     * `~/.cezar/server-instances/`. Self-describing so tooling can list what a
+     * host runs without re-deriving it from the filename.
+     */
+    instance: z.string().min(1).optional().catch(undefined),
+    /** Public domain this instance answers on (drives nginx `server_name` +
+     * the SSL cert). Absent for a plain HTTP / default install. */
+    domain: z.string().optional().catch(undefined),
+    /**
+     * External-reverse-proxy mode (`--external-proxy`): the box already has a
+     * front (Dokploy/Traefik, Coolify, Caddy, an existing nginx) that owns
+     * :80/:443 and provides TLS + auth. cezar then installs NO nginx and NO
+     * cert of its own — just the service — and that proxy routes to `bindHost`.
+     */
+    externalProxy: z.boolean().optional().catch(undefined),
+    /**
+     * Interface the cockpit binds. Loopback by default; an external-proxy
+     * install may need a host the proxy can actually reach (e.g. the docker
+     * bridge `172.17.0.1` when the proxy runs in a container).
+     */
+    bindHost: z.string().optional().catch(undefined),
+    /** Flips true only when every required step is `done`. */
+    installed: z.boolean().default(false).catch(false),
+    /** True when this record was written by a CEZ_DRY_RUN preview — a real
+     * install/uninstall treats it as no record at all (self-healing). */
+    dryRun: z.boolean().optional().catch(undefined),
+    /** ISO stamp set by the caller (Date.now is unavailable in some contexts). */
+    createdAt: z.string().optional().catch(undefined),
+    updatedAt: z.string().optional().catch(undefined),
+    primaryPort: z.number().int().positive().default(4321).catch(4321),
+    /** Public URL / identity user surfaced at the end — display only. */
+    publicUrl: z.string().optional().catch(undefined),
+    /** macOS+ngrok free tier: the tunnel URL changes across restarts. */
+    ephemeral: z.boolean().optional().catch(undefined),
+    // A single malformed entry degrades to a `failed` record (undo still runs
+    // from constants), never to losing every other step's ledger.
+    steps: z
+        .record(z.string(), stepOutcomeSchema.catch({ status: 'failed', created: null }))
+        .default({})
+        .catch({}),
+})
+    // Unknown top-level fields written by a newer cezar survive a load+save
+    // round-trip — the file's own additive-safe contract.
+    .passthrough();
+/** Freshly-initialized state (no install yet). */
+export function freshServerState() {
+    return serverStateSchema.parse({});
+}
+/**
+ * The interactive surface a step talks to. Implemented by `ui.ts` over
+ * `@clack/prompts`; declared here as a pure interface so `types.ts` (and the
+ * engine) never import the TUI library. Prompt methods resolve to the
+ * `CANCEL` sentinel instead of throwing when the user aborts.
+ */
+export const CANCEL = Symbol('cezar.ui.cancel');
+/** Thrown by `preflight` to stop with a clean, user-facing reason (no stack). */
+export class PreflightError extends Error {
+}
+//# sourceMappingURL=types.js.map

package/dist/server-install/types.js.map

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

package/dist/server-install/ui.d.ts

@@ -0,0 +1,42 @@
+import * as clack from '@clack/prompts';
+import { type Ui } from './types.ts';
+/**
+ * The interactive surface, implemented over `@clack/prompts` — the one place
+ * the TUI library is imported. `types.ts`, the engine and the steps talk to
+ * the `Ui` interface only, so `@clack/prompts` never enters the server/runtime
+ * import graph (AGENTS.md keeps that stack tiny).
+ *
+ * Every prompt maps clack's cancel symbol to the `CANCEL` sentinel instead of
+ * throwing, so a Ctrl-C mid-install is a value the engine can persist-and-exit
+ * on, not an exception.
+ */
+/** The subset of `@clack/prompts` the UI uses — injectable for unit tests. */
+export interface PromptBackend {
+    intro: typeof clack.intro;
+    outro: typeof clack.outro;
+    note: typeof clack.note;
+    log: typeof clack.log;
+    select: typeof clack.select;
+    multiselect: typeof clack.multiselect;
+    confirm: typeof clack.confirm;
+    text: typeof clack.text;
+    password: typeof clack.password;
+    spinner: typeof clack.spinner;
+    isCancel: typeof clack.isCancel;
+}
+/** The real interactive UI. */
+export declare function createClackUi(backend?: PromptBackend): Ui;
+/**
+ * Non-interactive UI for `--yes`, `CEZ_DRY_RUN`, and unit tests. Prompts resolve
+ * to deterministic safe defaults (initial value, or the first option, or ""),
+ * logs go to the console. It never touches stdin, so it can drive the engine
+ * headless. Optional `answers` override defaults per-prompt-message.
+ */
+export declare function createAutoUi(answers?: Record<string, unknown>, sink?: (m: string) => void, opts?: {
+    /**
+     * Enforce each prompt's `validate` on auto-answers (real `--yes` runs must
+     * fail closed on an unanswerable prompt). Off for CEZ_DRY_RUN previews,
+     * which must walk every step with placeholder-grade values.
+     */
+    strictValidate?: boolean;
+}): Ui;

package/dist/server-install/ui.js

@@ -0,0 +1,130 @@
+import * as clack from '@clack/prompts';
+import { CANCEL, PreflightError } from './types.js';
+import { StepAborted } from './steps.js';
+const realBackend = {
+    intro: clack.intro,
+    outro: clack.outro,
+    note: clack.note,
+    log: clack.log,
+    select: clack.select,
+    multiselect: clack.multiselect,
+    confirm: clack.confirm,
+    text: clack.text,
+    password: clack.password,
+    spinner: clack.spinner,
+    isCancel: clack.isCancel,
+};
+/** Map a clack result to `T | CANCEL`, never a thrown cancel. */
+function unwrap(value, isCancel) {
+    return isCancel(value) ? CANCEL : value;
+}
+/** The real interactive UI. */
+export function createClackUi(backend = realBackend) {
+    // clack renders a prompt at stdin-EOF and never resolves — a piped/ssh'd
+    // invocation would hang forever while holding the single-writer install
+    // lock. Refuse up front with the way out. (Injected fake backends are for
+    // tests, which have no TTY.)
+    if (backend === realBackend && (!process.stdin.isTTY || !process.stdout.isTTY)) {
+        throw new PreflightError('this terminal is not interactive — re-run from a TTY, or pass --yes (or CEZ_DRY_RUN=1) for non-interactive mode');
+    }
+    const wrapValidate = (validate) => validate ? (v) => validate(v ?? '') : undefined;
+    return {
+        intro: (m) => backend.intro(m),
+        outro: (m) => backend.outro(m),
+        note: (m, title) => backend.note(m, title),
+        // Raw, un-boxed: clack's note() draws a bordered box that breaks when a long
+        // command wraps. Write straight to stdout so the command stays selectable.
+        message: (m) => process.stdout.write(`\n${m}\n`),
+        info: (m) => backend.log.info(m),
+        success: (m) => backend.log.success(m),
+        warn: (m) => backend.log.warn(m),
+        error: (m) => backend.log.error(m),
+        async select(opts) {
+            // clack's `Option<Value>` is a conditional type that can't resolve against
+            // an unconstrained generic; cast the options and keep the explicit T.
+            const res = await backend.select({
+                message: opts.message,
+                options: opts.options,
+                initialValue: opts.initialValue,
+            });
+            return unwrap(res, backend.isCancel);
+        },
+        async multiselect(opts) {
+            const res = await backend.multiselect({
+                message: opts.message,
+                options: opts.options,
+                required: opts.required ?? false,
+            });
+            return unwrap(res, backend.isCancel);
+        },
+        async confirm(opts) {
+            return unwrap(await backend.confirm(opts), backend.isCancel);
+        },
+        async text(opts) {
+            return unwrap(await backend.text({ ...opts, validate: wrapValidate(opts.validate) }), backend.isCancel);
+        },
+        async password(opts) {
+            return unwrap(await backend.password({ ...opts, validate: wrapValidate(opts.validate) }), backend.isCancel);
+        },
+        spinner() {
+            const s = backend.spinner();
+            return {
+                start: (m) => s.start(m),
+                stop: (m) => s.stop(m),
+                message: (m) => s.message(m),
+            };
+        },
+    };
+}
+/**
+ * Non-interactive UI for `--yes`, `CEZ_DRY_RUN`, and unit tests. Prompts resolve
+ * to deterministic safe defaults (initial value, or the first option, or ""),
+ * logs go to the console. It never touches stdin, so it can drive the engine
+ * headless. Optional `answers` override defaults per-prompt-message.
+ */
+export function createAutoUi(answers = {}, sink = () => { }, opts = {}) {
+    const answer = (message, fallback) => (message in answers ? answers[message] : fallback);
+    const checkValid = (message, v, validate) => {
+        if (!opts.strictValidate)
+            return;
+        const invalid = validate?.(v);
+        if (invalid !== undefined) {
+            throw new StepAborted(`cannot auto-answer "${message}" (${invalid}) — run without --yes to answer it`);
+        }
+    };
+    return {
+        intro: sink,
+        outro: sink,
+        note: (m) => sink(m),
+        message: sink,
+        info: sink,
+        success: sink,
+        warn: sink,
+        error: sink,
+        async select(opts) {
+            return answer(opts.message, opts.initialValue ?? opts.options[0]?.value);
+        },
+        async multiselect(opts) {
+            return answer(opts.message, []);
+        },
+        async confirm(opts) {
+            return answer(opts.message, opts.initialValue ?? true);
+        },
+        // A placeholder is a HINT, never an answer — auto-adopting it turned the
+        // example domain `cezar.ngrok.app` into real input under `--yes`.
+        async text(o) {
+            const v = String(answer(o.message, o.initialValue ?? ''));
+            checkValid(o.message, v, o.validate);
+            return v;
+        },
+        async password(o) {
+            const v = String(answer(o.message, ''));
+            checkValid(o.message, v, o.validate);
+            return v;
+        },
+        spinner() {
+            return { start: (m) => m && sink(m), stop: (m) => m && sink(m), message: (m) => sink(m) };
+        },
+    };
+}
+//# sourceMappingURL=ui.js.map

package/dist/server-install/ui.js.map

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

package/dist/skills-banner.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Promotes `open-mercato/skills` (#391) — cezar's built-in default skills source
+ * (`DEFAULT_SKILLS_REPOS` in `src/config.ts`) that today only surfaces in `--help`. Split out of
+ * `src/index.ts` so it is testable without importing `index.ts` (which runs `main()` on import).
+ * It once had a cockpit twin to stay in step with; #603 replaced that with the opt-in
+ * `packages/web/src/components/skills-import-panel.tsx`, so the terminal is now the only surface
+ * that renders the promo.
+ *
+ * Printed on `serve` start — a few lines in an already-chatty startup block. It has two off
+ * switches, because a promo that cannot be silenced is a nag:
+ *  - `CEZ_NO_BANNER=1` in the environment, and
+ *  - `dismissedSkillsBanner` in `.ai/cezar/ui-state.json` — written by the cockpit banner until
+ *    #603 removed it. The flag is still honoured, so anyone who dismissed it back then stays
+ *    silenced; nothing writes it today.
+ * Reading that flag follows the `src/config.ts` rule: a missing/unreadable/malformed state file
+ * degrades to showing the banner, never to a crash or a blocked startup.
+ */
+export declare const SKILLS_BANNER_LINES: readonly string[];
+/** Both off switches in one place. Never throws. */
+export declare function shouldShowSkillsBanner(repoRoot: string): Promise<boolean>;
+/** The `serve` startup banner. `log` is injectable so the wiring is testable. */
+export declare function printSkillsBanner(repoRoot: string, log?: (line?: string) => void): Promise<void>;

package/dist/skills-banner.js

@@ -0,0 +1,41 @@
+import { readUiState } from './ui-state.js';
+/**
+ * Promotes `open-mercato/skills` (#391) — cezar's built-in default skills source
+ * (`DEFAULT_SKILLS_REPOS` in `src/config.ts`) that today only surfaces in `--help`. Split out of
+ * `src/index.ts` so it is testable without importing `index.ts` (which runs `main()` on import).
+ * It once had a cockpit twin to stay in step with; #603 replaced that with the opt-in
+ * `packages/web/src/components/skills-import-panel.tsx`, so the terminal is now the only surface
+ * that renders the promo.
+ *
+ * Printed on `serve` start — a few lines in an already-chatty startup block. It has two off
+ * switches, because a promo that cannot be silenced is a nag:
+ *  - `CEZ_NO_BANNER=1` in the environment, and
+ *  - `dismissedSkillsBanner` in `.ai/cezar/ui-state.json` — written by the cockpit banner until
+ *    #603 removed it. The flag is still honoured, so anyone who dismissed it back then stays
+ *    silenced; nothing writes it today.
+ * Reading that flag follows the `src/config.ts` rule: a missing/unreadable/malformed state file
+ * degrades to showing the banner, never to a crash or a blocked startup.
+ */
+export const SKILLS_BANNER_LINES = [
+    '  🤖 Make the most of parallel coding with our AI skills',
+    '  open-mercato/skills: reusable, technology-agnostic agent skills for PR',
+    '  creation, code review, CI stabilisation, spec writing & more.',
+    '  cezar already loads them for you — Skills → Refresh in the cockpit gets the latest.',
+    "  To use them outside cezar:  npx skills add open-mercato/skills --skill '*'",
+];
+/** Both off switches in one place. Never throws. */
+export async function shouldShowSkillsBanner(repoRoot) {
+    if (process.env.CEZ_NO_BANNER === '1')
+        return false;
+    const uiState = await readUiState(repoRoot);
+    return uiState.dismissedSkillsBanner !== true;
+}
+/** The `serve` startup banner. `log` is injectable so the wiring is testable. */
+export async function printSkillsBanner(repoRoot, log = console.log) {
+    if (!(await shouldShowSkillsBanner(repoRoot)))
+        return;
+    for (const line of SKILLS_BANNER_LINES)
+        log(line);
+    log();
+}
+//# sourceMappingURL=skills-banner.js.map

package/dist/skills-banner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills-banner.js","sourceRoot":"","sources":["../src/skills-banner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAsB;IACpD,0DAA0D;IAC1D,0EAA0E;IAC1E,iEAAiE;IACjE,uFAAuF;IACvF,8EAA8E;CAC/E,CAAC;AAEF,oDAAoD;AACpD,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,QAAgB;IAC3D,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IACpD,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC5C,OAAO,OAAO,CAAC,qBAAqB,KAAK,IAAI,CAAC;AAChD,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAgB,EAChB,GAAG,GAA4B,OAAO,CAAC,GAAG;IAE1C,IAAI,CAAC,CAAC,MAAM,sBAAsB,CAAC,QAAQ,CAAC,CAAC;QAAE,OAAO;IACtD,KAAK,MAAM,IAAI,IAAI,mBAAmB;QAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IAClD,GAAG,EAAE,CAAC;AACR,CAAC"}

package/dist/skills-remote.d.ts

@@ -0,0 +1,84 @@
+import { type SkillsRepoSource } from './config.ts';
+import { type Skill } from './skills.ts';
+/**
+ * The git remote for a configured source, or null when the value is unsafe to
+ * hand to `git` (#428). Team-skill repos are code-trusted — their skill bodies
+ * become agent system prompts — but the *string* is attacker-influenceable, so
+ * it must never be able to select a transport helper or pose as a git option.
+ * We accept exactly:
+ *  - `owner/name`         GitHub shorthand → canonical https
+ *  - `https://` `http://` web URLs
+ *  - `ssh://…` or scp-like `git@host:path`
+ *  - a local path (`/abs`, `./`, `../`, `~/…`, `C:\…`) or `file://…`
+ * and reject the RCE/argument-injection surface: a leading `-`, the `::`
+ * remote-helper syntax (`ext::sh -c …`, `fd::…`), and any other URL scheme.
+ *
+ * Every reject here maps to a real vector. Shapes that are merely *unusual* —
+ * a Windows drive path, `~/…` — stay accepted: `BACKWARD_COMPATIBILITY.md` §5
+ * protects the `skillsRepos` source shape, so narrowing it is a breaking change
+ * and needs a migration path, not a silent refusal.
+ */
+export declare function safeRemoteFor(repo: string): string | null;
+/**
+ * A ref safe to pass to `git` as a positional revision (#428): a branch, tag,
+ * or commit SHA. Rejects a leading `-` (argument injection against git's option
+ * surface), range/pathspec metacharacters, and anything outside the git
+ * ref-name charset — so `${ref}:${path}` in `git show` can never be a `-`-flag.
+ */
+export declare function isSafeRef(ref: string): boolean;
+/** A full commit SHA (sha-1 or sha-256) — a pinned, immutable ref (#428). */
+export declare function isPinnedSha(ref: string): boolean;
+/** Stable cache directory name: the last two path segments, `owner__name`. */
+export declare function bareDirFor(repo: string): string;
+/** Clone the skills repo bare (no checkout) into the global cache, once. */
+export declare function ensureBareClone(repo: string): Promise<{
+    bareDir: string;
+    created: boolean;
+}>;
+/** "Refresh" — update every branch head in the bare clone from origin. */
+export declare function fetchAll(bareDir: string): Promise<void>;
+/**
+ * Read one file from the bare clone at the source's ref. Null on any failure.
+ * `atCommit` pins the read to an already-resolved commit, so a caller listing
+ * many files reads them all at the same commit (and skips re-resolving).
+ */
+export declare function readRemoteSkill(src: SkillsRepoSource, path: string, atCommit?: string): Promise<string | null>;
+/**
+ * List every skill the repo defines at `src.ref`. Reads from the local bare
+ * clone only — no network. Empty list when the clone doesn't exist yet or
+ * the ref can't be resolved.
+ */
+export declare function listRemoteSkills(src: SkillsRepoSource): Promise<Skill[]>;
+/**
+ * Copy a directory skill (SKILL.md + references/…) out of the bare clone into
+ * `<repoRoot>/.claude/skills/<name>/` so claude sees the references on disk,
+ * and keep it out of the user's git via `.git/info/exclude`. Returns false
+ * when there is nothing to materialize (not a directory skill, no clone…).
+ */
+export declare function materializeSkillDir(repoRoot: string, skill: Skill): Promise<boolean>;
+/**
+ * Whether a passive (non-`refresh`) load should `git fetch` an existing bare
+ * clone: yes on the first touch this process, and yes once the last fetch is
+ * older than `ttlMs`. Pure so the freshness policy is unit-tested without git.
+ */
+export declare function shouldPassiveFetch(opts: {
+    attempted: boolean;
+    fetchedAt: number;
+    now: number;
+    ttlMs: number;
+}): boolean;
+/**
+ * The current team-skill list for this project, straight from memory. The
+ * first call per `repoRoot` kicks off an async background load (clone + list)
+ * and returns immediately — the GUI refetches, so remote skills appear moments
+ * later instead of blocking the first `GET /api/skills`.
+ */
+export declare function getTeamSkillsCached(repoRoot: string): Skill[];
+/**
+ * Wait for the same non-refreshing load kicked off by `getTeamSkillsCached`.
+ * The normal catalog read stays immediate; callers use this only for a
+ * background convergence read after they have already rendered local skills.
+ */
+export declare function waitForTeamSkills(repoRoot: string): Promise<Skill[]>;
+/** Refresh: clone missing sources, `git fetch` existing ones, reload the list. */
+export declare function refreshTeamSkills(repoRoot: string): Promise<Skill[]>;