@open-mercato/cezar 0.1.5-pr506.357

package/dist/server-install/types.js

@@ -0,0 +1,98 @@
+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),
+    /** 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.js';
+/**
+ * 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,21 @@
+/**
+ * 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 the CLI banner has one source of truth the web cockpit copy
+ * (`web/app/src/components/skills-banner.tsx`) can be kept in step with, and so it is testable
+ * without importing `index.ts` (which runs `main()` on import).
+ *
+ * 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` — the SAME flag the cockpit banner
+ *    persists, so dismissing it there also silences the terminal and the two surfaces tell one
+ *    story.
+ * 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,40 @@
+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 the CLI banner has one source of truth the web cockpit copy
+ * (`web/app/src/components/skills-banner.tsx`) can be kept in step with, and so it is testable
+ * without importing `index.ts` (which runs `main()` on import).
+ *
+ * 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` — the SAME flag the cockpit banner
+ *    persists, so dismissing it there also silences the terminal and the two surfaces tell one
+ *    story.
+ * 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;;;;;;;;;;;;;;;GAeG;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,MAA+B,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,35 @@
+import { type SkillsRepoSource } from './config.js';
+import { type Skill } from './skills.js';
+/** 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. */
+export declare function readRemoteSkill(src: SkillsRepoSource, path: 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>;
+/**
+ * The current team-skill list, straight from memory. The first call 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[];
+/** Refresh: clone missing sources, `git fetch` existing ones, reload the list. */
+export declare function refreshTeamSkills(repoRoot: string): Promise<Skill[]>;

package/dist/skills-remote.js

@@ -0,0 +1,266 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { loadConfig } from './config.js';
+import { parseFrontmatter } from './skills.js';
+/**
+ * Team skills from remote git repos (spec 005), janitor-style: a bare clone
+ * without a checkout, listed with `git ls-tree` and read with `git show`.
+ * The cache lives in `~/.cache/cez/skills/<owner>__<name>/` — global, so one
+ * fetch serves every project. Everything degrades: no network / no access to
+ * the skills repo means the team skills quietly disappear from the list while
+ * local skills keep working. Nothing here ever blocks startup.
+ */
+const LIST_TIMEOUT_MS = 10_000; // ls-tree / show / rev-parse
+const CLONE_TIMEOUT_MS = 60_000; // clone / fetch
+function git(args, timeoutMs, cwd) {
+    return new Promise((resolve) => {
+        execFile('git', args, { cwd, timeout: timeoutMs, killSignal: 'SIGKILL', maxBuffer: 16 * 1024 * 1024, encoding: 'utf8' }, (err, stdout, stderr) => resolve({ ok: !err, stdout: stdout ?? '', stderr: stderr ?? '' }));
+    });
+}
+/** `owner/name` shorthand → GitHub HTTPS; anything else (URL, file://, local path) as-is. */
+function remoteFor(repo) {
+    return /^[\w.-]+\/[\w.-]+$/.test(repo) ? `https://github.com/${repo}.git` : repo;
+}
+/** Stable cache directory name: the last two path segments, `owner__name`. */
+export function bareDirFor(repo) {
+    const trimmed = repo
+        .replace(/\/+$/, '')
+        .replace(/\.git$/, '')
+        .replace(/^[a-z+]+:\/\//i, '')
+        .replace(/^~\//, '');
+    const segments = trimmed.split(/[/:]/).filter(Boolean).map(sanitizeSegment);
+    const key = segments.slice(-2).join('__') || 'skills';
+    return join(homedir(), '.cache', 'cez', 'skills', key);
+}
+function sanitizeSegment(s) {
+    return s.replace(/[^\w.-]/g, '-');
+}
+/** Clone the skills repo bare (no checkout) into the global cache, once. */
+export async function ensureBareClone(repo) {
+    const bareDir = bareDirFor(repo);
+    if (existsSync(join(bareDir, 'HEAD')))
+        return { bareDir, created: false };
+    await mkdir(dirname(bareDir), { recursive: true });
+    const remote = remoteFor(repo);
+    const res = await git(['clone', '--bare', remote, bareDir], CLONE_TIMEOUT_MS);
+    if (!res.ok)
+        throw new Error(`git clone --bare ${remote} failed: ${res.stderr.trim()}`);
+    return { bareDir, created: true };
+}
+/** "Refresh" — update every branch head in the bare clone from origin. */
+export async function fetchAll(bareDir) {
+    const res = await git(['fetch', 'origin', '--prune', '+refs/heads/*:refs/heads/*'], CLONE_TIMEOUT_MS, bareDir);
+    if (!res.ok)
+        throw new Error(`git fetch failed: ${res.stderr.trim() || res.stdout.trim()}`);
+}
+async function resolveRef(bareDir, ref) {
+    for (const candidate of [ref, `refs/heads/${ref}`, 'HEAD']) {
+        const probe = await git(['rev-parse', '--verify', '--quiet', candidate], LIST_TIMEOUT_MS, bareDir);
+        if (probe.ok)
+            return candidate;
+    }
+    return ref;
+}
+/**
+ * Match the janitor conventions plus our own:
+ *  - `**\/SKILL.md`          → skill named after the parent directory (with references/)
+ *  - `**\/commands/<n>.md`   → skill `<n>`
+ *  - `.ai/skills/**\/*.md` or `.ai/cezar/skills/**\/*.md` → frontmatter/basename name
+ */
+function matchSkillPath(line) {
+    if (line === 'SKILL.md' || line.endsWith('/SKILL.md')) {
+        const parts = line.split('/');
+        if (parts.length < 2)
+            return null;
+        const parent = parts[parts.length - 2];
+        return parent && parent !== '.' ? { name: parent, kind: 'skill' } : null;
+    }
+    const cmd = /(?:^|\/)commands\/([^/]+)\.md$/.exec(line);
+    if (cmd)
+        return { name: cmd[1], kind: 'command' };
+    if (/(?:^|\/)\.ai\/(?:cezar\/)?skills\/.+\.md$/.test(line))
+        return { name: null, kind: 'markdown' };
+    return null;
+}
+/** Read one file from the bare clone at the source's ref. Null on any failure. */
+export async function readRemoteSkill(src, path) {
+    const bareDir = bareDirFor(src.repo);
+    if (!existsSync(join(bareDir, 'HEAD')))
+        return null;
+    const ref = await resolveRef(bareDir, src.ref);
+    const res = await git(['show', `${ref}:${path}`], LIST_TIMEOUT_MS, bareDir);
+    return res.ok ? res.stdout : 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 async function listRemoteSkills(src) {
+    const bareDir = bareDirFor(src.repo);
+    if (!existsSync(join(bareDir, 'HEAD')))
+        return [];
+    const ref = await resolveRef(bareDir, src.ref);
+    const ls = await git(['ls-tree', '-r', '--name-only', ref], LIST_TIMEOUT_MS, bareDir);
+    if (!ls.ok)
+        return [];
+    const skills = [];
+    const seen = new Set();
+    for (const line of ls.stdout.split('\n')) {
+        if (!line)
+            continue;
+        const hit = matchSkillPath(line);
+        if (!hit)
+            continue;
+        const raw = await readRemoteSkill(src, line);
+        if (raw === null)
+            continue;
+        const { frontmatter, body } = parseFrontmatter(raw);
+        const name = hit.name ??
+            (typeof frontmatter.name === 'string' && frontmatter.name.trim()
+                ? frontmatter.name.trim()
+                : basename(line, '.md'));
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        const description = typeof frontmatter.description === 'string' && frontmatter.description.trim()
+            ? frontmatter.description.trim()
+            : undefined;
+        skills.push({
+            name,
+            description,
+            body,
+            path: `${src.repo}@${src.ref}:${line}`,
+            source: 'team',
+            team: { repo: src.repo, ref: src.ref, path: line, dir: hit.kind === 'skill' },
+        });
+    }
+    return skills;
+}
+// ---- materialization (directory skills) ---------------------------------------
+/**
+ * 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 async function materializeSkillDir(repoRoot, skill) {
+    if (!skill.team?.dir || !skill.team.path.endsWith('SKILL.md'))
+        return false;
+    const bareDir = bareDirFor(skill.team.repo);
+    if (!existsSync(join(bareDir, 'HEAD')))
+        return false;
+    const ref = await resolveRef(bareDir, skill.team.ref);
+    const srcDir = skill.team.path.slice(0, -'/SKILL.md'.length);
+    const ls = await git(['ls-tree', '-r', '--name-only', ref, '--', srcDir], LIST_TIMEOUT_MS, bareDir);
+    if (!ls.ok)
+        return false;
+    const destDir = join(repoRoot, '.claude', 'skills', skill.name);
+    let wrote = 0;
+    for (const file of ls.stdout.split('\n').filter(Boolean)) {
+        const rel = file.slice(srcDir.length + 1);
+        // git paths are repo-relative and normalized, but never trust them blindly.
+        if (!rel || rel.split('/').includes('..'))
+            continue;
+        const show = await git(['show', `${ref}:${file}`], LIST_TIMEOUT_MS, bareDir);
+        if (!show.ok)
+            continue;
+        const target = join(destDir, rel);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, show.stdout, 'utf8');
+        wrote++;
+    }
+    if (wrote === 0)
+        return false;
+    await excludeFromGit(repoRoot, `.claude/skills/${skill.name}/`);
+    return true;
+}
+/** Append a pattern to git's `info/exclude` (idempotent, non-fatal). */
+async function excludeFromGit(repoRoot, pattern) {
+    try {
+        // Resolve the real exclude file: in a linked worktree (spec 006) `.git`
+        // is a file and `info/exclude` lives in the shared common dir — which
+        // also means one exclude entry covers every task worktree.
+        const probe = await git(['rev-parse', '--path-format=absolute', '--git-common-dir'], LIST_TIMEOUT_MS, repoRoot);
+        const gitDir = probe.ok && probe.stdout.trim() ? probe.stdout.trim() : join(repoRoot, '.git');
+        const excludePath = join(gitDir, 'info', 'exclude');
+        let prev = '';
+        try {
+            prev = await readFile(excludePath, 'utf8');
+        }
+        catch {
+            // no exclude file yet
+        }
+        if (prev.split('\n').includes(pattern))
+            return;
+        await mkdir(dirname(excludePath), { recursive: true });
+        await writeFile(excludePath, prev + (prev && !prev.endsWith('\n') ? '\n' : '') + pattern + '\n', 'utf8');
+    }
+    catch {
+        // non-fatal — `.git` might be a linked file (worktree) or absent entirely
+    }
+}
+// ---- in-process cache ----------------------------------------------------------
+// Clone attempts are expensive when the network is down (git can hang on
+// DNS/TCP), so each source gets one implicit attempt per process. "Refresh"
+// always retries.
+const cloneAttempted = new Set();
+let teamSkills = [];
+let firstLoadStarted = false;
+/**
+ * The current team-skill list, straight from memory. The first call 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 function getTeamSkillsCached(repoRoot) {
+    if (!firstLoadStarted) {
+        firstLoadStarted = true;
+        void loadTeamSkills(repoRoot, false).catch(() => undefined);
+    }
+    return teamSkills;
+}
+/** Refresh: clone missing sources, `git fetch` existing ones, reload the list. */
+export async function refreshTeamSkills(repoRoot) {
+    firstLoadStarted = true;
+    return loadTeamSkills(repoRoot, true);
+}
+async function loadTeamSkills(repoRoot, refresh) {
+    const config = await loadConfig(repoRoot);
+    const out = [];
+    const seen = new Set();
+    for (const src of config.skillsRepos) {
+        try {
+            if (refresh) {
+                const { bareDir, created } = await ensureBareClone(src.repo);
+                if (!created)
+                    await fetchAll(bareDir);
+                cloneAttempted.add(src.repo);
+            }
+            else if (!cloneAttempted.has(src.repo)) {
+                cloneAttempted.add(src.repo);
+                await ensureBareClone(src.repo);
+            }
+        }
+        catch {
+            // offline / no access — list whatever an older clone has (or nothing)
+        }
+        try {
+            for (const skill of await listRemoteSkills(src)) {
+                if (seen.has(skill.name))
+                    continue;
+                seen.add(skill.name);
+                out.push(skill);
+            }
+        }
+        catch {
+            // degrade: this source contributes nothing
+        }
+    }
+    teamSkills = out;
+    return out;
+}
+//# sourceMappingURL=skills-remote.js.map