@loompad/cli 0.1.0 → 1.1.1

package/dist/core/shift.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Night Shift: line up work, go to sleep, wake up to a report you can trust.
+ *
+ * Each task runs in its own chat, one after another, through the queue. While
+ * the shift runs, Proof checks every "done" against what ran and a clean
+ * re-run, the loop watch nudges an agent going in circles, and Quota Relay
+ * hands work on when an agent runs out. This file is the part that reads a
+ * task's chat afterwards and says, plainly, how it went. Pure.
+ */
+import type { LoomEvent } from "../types.js";
+export type ShiftTaskStatus = "verified" | "done" | "didnt_hold" | "failed" | "needs_you" | "not_started" | "running";
+export interface ShiftTask {
+    text: string;
+    chat: string;
+    /** The queue item it went out as, until it's dispatched. */
+    queueId?: string;
+    /** Set once the shift knows it won't run (stopped by the clock or the budget). */
+    skipped?: boolean;
+}
+export interface ShiftConfig {
+    id: string;
+    startedAt: number;
+    /** Who takes the tasks; absent → whoever the queue would pick (auto). */
+    to?: string;
+    /** Stop starting new tasks after this moment (epoch ms). */
+    until?: number;
+    /** Stop starting new tasks once the shift has spent this much. */
+    maxUsd?: number;
+    tasks: ShiftTask[];
+    /** Set when it stops early, with why. */
+    stopped?: string;
+    /** Set once the report has gone out. */
+    reportedAt?: number;
+}
+export interface TaskOutcome {
+    text: string;
+    chat: string;
+    status: ShiftTaskStatus;
+    agent?: string;
+    /** Proof's one-line verdict, when it checked. */
+    headline?: string;
+    /** Times the loop watch caught it going in circles. */
+    loops: number;
+    files: string[];
+    costUsd: number;
+    ms: number;
+    error?: string;
+    question?: string;
+}
+export interface ShiftReport {
+    shiftId: string;
+    startedAt: number;
+    endedAt: number;
+    tasks: TaskOutcome[];
+    counts: Record<ShiftTaskStatus, number>;
+    costUsd: number;
+    stopped?: string;
+    /** "4 tasks: 3 verified, 1 needs you" */
+    summary: string;
+}
+/** How one task went, from its chat's events. */
+export declare function outcomeOf(task: ShiftTask, events: LoomEvent[], opts?: {
+    queued?: boolean;
+}): TaskOutcome;
+export declare function report(shift: ShiftConfig, outcomes: TaskOutcome[], endedAt?: number): ShiftReport;
+/** "7:00", "07:30", "7am", "6:45 pm", or an ISO time → the next such moment after `now`. */
+export declare function parseUntil(raw: string | number | undefined, now?: number): number | undefined;
+/** One task per line; blank lines and "- " / "1. " list markers dropped. */
+export declare function parseTasks(raw: string | string[]): string[];

package/dist/core/shift.js

@@ -0,0 +1,120 @@
+/**
+ * Night Shift: line up work, go to sleep, wake up to a report you can trust.
+ *
+ * Each task runs in its own chat, one after another, through the queue. While
+ * the shift runs, Proof checks every "done" against what ran and a clean
+ * re-run, the loop watch nudges an agent going in circles, and Quota Relay
+ * hands work on when an agent runs out. This file is the part that reads a
+ * task's chat afterwards and says, plainly, how it went. Pure.
+ */
+/** How one task went, from its chat's events. */
+export function outcomeOf(task, events, opts = {}) {
+    const base = { text: task.text, chat: task.chat, status: "not_started", loops: 0, files: [], costUsd: 0, ms: 0 };
+    if (opts.queued || task.skipped)
+        return base;
+    const files = new Set();
+    let lastDone, lastProof, lastAsk, lastSay, lastAnswer, lastError;
+    for (const e of events) {
+        const p = e.payload ?? {};
+        if (e.kind === "run_complete" && e.agentId) {
+            lastDone = e;
+            base.ms += Number(p.durationMs ?? 0) || 0;
+            base.agent = e.agentId;
+        }
+        else if (e.kind === "proof")
+            lastProof = e;
+        else if (e.kind === "needs_input")
+            lastAsk = e;
+        else if (e.kind === "message" && !e.agentId)
+            lastSay = e;
+        else if (e.kind === "error" && e.agentId)
+            lastError = e;
+        else if (e.kind === "turn_diff")
+            for (const f of p.files ?? [])
+                files.add(f.path);
+        else if (e.kind === "status" && p.state === "question_answered")
+            lastAnswer = e;
+        else if (e.kind === "status" && p.state === "loop_detected")
+            base.loops++;
+        else if (e.kind === "status" && p.state === "turn_cost")
+            base.costUsd += Number(p.costUsd ?? 0) || 0;
+    }
+    base.files = [...files];
+    base.costUsd = Math.round(base.costUsd * 10_000) / 10_000;
+    if (lastDone?.payload.error)
+        return { ...base, status: "failed", error: String(lastDone.payload.error).slice(0, 300) };
+    // a turn that died with an error (no clean end after it, nothing said since)
+    if (lastError && (!lastDone || lastError.id > lastDone.id) && (!lastSay || lastError.id > lastSay.id)) {
+        return { ...base, status: "failed", agent: lastError.agentId ?? base.agent, error: String(lastError.payload.message ?? "it stopped with an error").slice(0, 300) };
+    }
+    // an open question: asked after the last thing you (or the queue) said, and not answered — whether the
+    // agent's turn is parked on it or ended on it, it's waiting for you
+    if (lastAsk && (!lastSay || lastAsk.id > lastSay.id) && (!lastAnswer || lastAsk.id > lastAnswer.id)) {
+        return { ...base, status: "needs_you", agent: lastAsk.agentId ?? base.agent, question: String(lastAsk.payload.question ?? "") };
+    }
+    if (!lastDone)
+        return { ...base, status: lastSay ? "running" : "not_started" };
+    // Proof only counts when it checked the last turn (a nudge can come after it)
+    if (lastProof && lastProof.id > lastDone.id) {
+        const v = String(lastProof.payload.verdict ?? "");
+        const headline = String(lastProof.payload.headline ?? "");
+        if (v === "contradicted")
+            return { ...base, status: "didnt_hold", headline };
+        if (v === "verified")
+            return { ...base, status: "verified", headline };
+        return { ...base, status: "done", headline };
+    }
+    return { ...base, status: "done" };
+}
+const WORDS = {
+    verified: "verified", done: "done (not checked)", didnt_hold: "didn't hold", failed: "failed",
+    needs_you: "need you", not_started: "not started", running: "still running",
+};
+const ORDER = ["verified", "done", "didnt_hold", "failed", "needs_you", "running", "not_started"];
+export function report(shift, outcomes, endedAt = Date.now()) {
+    const counts = Object.fromEntries(ORDER.map((s) => [s, 0]));
+    for (const o of outcomes)
+        counts[o.status]++;
+    const parts = ORDER.filter((s) => counts[s]).map((s) => `${counts[s]} ${s === "needs_you" && counts[s] === 1 ? "needs you" : WORDS[s]}`);
+    const n = outcomes.length;
+    return {
+        shiftId: shift.id, startedAt: shift.startedAt, endedAt, tasks: outcomes, counts,
+        costUsd: Math.round(outcomes.reduce((x, o) => x + o.costUsd, 0) * 10_000) / 10_000,
+        ...(shift.stopped ? { stopped: shift.stopped } : {}),
+        summary: `${n} task${n === 1 ? "" : "s"}: ${parts.join(", ")}`,
+    };
+}
+/** "7:00", "07:30", "7am", "6:45 pm", or an ISO time → the next such moment after `now`. */
+export function parseUntil(raw, now = Date.now()) {
+    if (raw === undefined || raw === "")
+        return undefined;
+    if (typeof raw === "number")
+        return Number.isFinite(raw) ? raw : undefined;
+    const m = /^\s*(\d{1,2})(?::(\d{2}))?\s*(am|pm)?\s*$/i.exec(raw);
+    if (m) {
+        let h = Number(m[1]);
+        const min = Number(m[2] ?? 0);
+        const ap = m[3]?.toLowerCase();
+        if (ap === "pm" && h < 12)
+            h += 12;
+        if (ap === "am" && h === 12)
+            h = 0;
+        if (h > 23 || min > 59)
+            throw new Error(`"${raw}" isn't a time of day`);
+        const d = new Date(now);
+        d.setHours(h, min, 0, 0);
+        if (d.getTime() <= now)
+            d.setDate(d.getDate() + 1);
+        return d.getTime();
+    }
+    const t = Date.parse(raw);
+    if (!Number.isFinite(t))
+        throw new Error(`"${raw}" isn't a time I can read — try 7:00, 6:30am or an ISO time`);
+    return t;
+}
+/** One task per line; blank lines and "- " / "1. " list markers dropped. */
+export function parseTasks(raw) {
+    const lines = Array.isArray(raw) ? raw : raw.split("\n");
+    return lines.map((l) => String(l).replace(/^\s*(?:[-*•]|\d+[.)])\s+/, "").trim()).filter(Boolean).slice(0, 50);
+}
+//# sourceMappingURL=shift.js.map

package/dist/core/shift.js.map

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

package/dist/core/skill-install.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Installing a skill — copying somebody else's SKILL.md into this project.
+ *
+ * Discovery (core/skills.ts) answers "what do I already have". This answers the
+ * other half: a skill you found in a gist, a repo, or a folder on disk becomes
+ * `<projectDir>/skills/<id>/`, which is the first root the loader scans and the
+ * only one Loom is allowed to write to.
+ *
+ * ## Why so much of this file is refusal
+ *
+ * Both entry points take a string from an HTTP body and turn it into filesystem
+ * writes, so the interesting cases are all the ones that must not happen:
+ *
+ *   - **The id is a path.** `id` is joined onto `<projectDir>/skills/`, so an id
+ *     of `../../.ssh` writes outside the project. It is validated against a
+ *     character class rather than sanitised, because silently rewriting a
+ *     malicious id into a benign one installs a skill under a name the caller
+ *     didn't ask for, and then everything downstream is about the wrong skill.
+ *
+ *   - **The URL is a command.** `installSkillFromGit` runs git. Every argument
+ *     goes through `execFile` with an array — never a shell string — so a URL
+ *     containing `;` or `$(…)` is a URL git will fail to clone, not a command.
+ *     The URL is also checked to be http(s) or ssh git first: git happily
+ *     accepts `ext::sh -c …` and `--upload-pack=…` as "remotes", and those are
+ *     code execution with extra steps.
+ *
+ *   - **An overwrite is silent.** Installing over an existing skill destroys
+ *     whatever the user wrote there. It needs `force`, and the error says which
+ *     id collided so the UI can offer the choice instead of guessing.
+ *
+ * A clone is bounded (90s) and runs with `GIT_TERMINAL_PROMPT=0`: a private repo
+ * must fail as a private repo, not hang a request forever on a credential prompt
+ * that nobody is at a terminal to answer.
+ */
+/** A refusal with a reason the UI can show verbatim. Distinct so routes can 400 it. */
+export declare class SkillInstallError extends Error {
+    constructor(message: string);
+}
+/** Where an installed skill came from — recorded so the caller can say so. */
+export type SkillInstallOrigin = "dir" | "git";
+export interface SkillInstallResult {
+    /** The directory name under `<projectDir>/skills/`, and the skill's id. */
+    id: string;
+    /** The `name:` from the frontmatter. */
+    name: string;
+    description: string;
+    /** Absolute path to the installed directory. */
+    dir: string;
+    /** Absolute path to the installed SKILL.md. */
+    path: string;
+    /** How it arrived: a local directory, or a clone. */
+    from: SkillInstallOrigin;
+    /** The exact source string the caller gave — the src dir, or the git URL. */
+    source: string;
+    /** True when an existing skill of the same id was replaced (needs `force`). */
+    replaced: boolean;
+    /** With #all: the other skills installed from the same repo. */
+    also?: string[];
+}
+export interface InstallOptions {
+    /** Replace an existing skill of the same id instead of refusing. */
+    force?: boolean;
+    /**
+     * Install under this id instead of the source directory's name. Validated
+     * exactly like a derived id — the caller doesn't get a shortcut past the
+     * traversal check by supplying the id itself.
+     */
+    id?: string;
+}
+/**
+ * Copy a skill directory into the project.
+ *
+ * The whole directory comes across, not just SKILL.md: skills reference scripts
+ * and `references/` files next to them, and a skill installed without its
+ * attachments is a skill whose instructions point at nothing.
+ */
+/**
+ * Author a skill in place: scaffold `skills/<id>/SKILL.md`, validated.
+ *
+ * Skills could be browsed and installed but never written — authoring one
+ * meant knowing the frontmatter convention by heart and hand-building the
+ * directory. The validation is the same reader the roster uses (parseSkillMd),
+ * so a skill this accepts is a skill the loader will actually offer: refusing
+ * to write anything the roster would silently drop is the whole point.
+ */
+export declare function authorSkill(projectDir: string, input: {
+    id: string;
+    name: string;
+    description: string;
+    body?: string;
+}): {
+    dir: string;
+    file: string;
+};
+export declare function installSkillFromDir(srcDir: string, projectDir: string, opts?: InstallOptions): SkillInstallResult;
+/**
+ * Clone a repository and install the skill inside it.
+ *
+ * `--depth 1` because history is irrelevant to a directory of markdown, and a
+ * shallow clone of a large skills repo is the difference between a second and a
+ * minute. The SKILL.md is looked for at the repo root first and then one level
+ * down — the two layouts people actually publish ("this repo IS a skill" and
+ * "this repo is a folder of skills"). Deeper than that is ambiguous: a repo with
+ * `a/b/SKILL.md` and `c/d/SKILL.md` has no obvious answer, and picking one is
+ * how you install something the user didn't choose.
+ *
+ * The temp clone is removed on every path, including the failures.
+ */
+export declare function installSkillFromGit(url: string, projectDir: string, opts?: InstallOptions & {
+    timeoutMs?: number;
+}): Promise<SkillInstallResult>;
+/**
+ * The repo root if it is itself a skill, else the first child directory that is.
+ *
+ * Exported for the tests: the two layouts this handles are the whole of the
+ * git installer's judgement, and a clone is the one part of that path a test
+ * can't reach offline.
+ */
+export declare function findSkillDir(root: string): string | null;
+/**
+ * Every skill in a checkout: the root if it is one; else each child directory
+ * that is; else each one under skills/ (and .claude/skills/) — the layouts
+ * people publish.
+ */
+export declare function findSkillDirs(root: string): string[];

package/dist/core/skill-install.js

@@ -0,0 +1,328 @@
+/**
+ * Installing a skill — copying somebody else's SKILL.md into this project.
+ *
+ * Discovery (core/skills.ts) answers "what do I already have". This answers the
+ * other half: a skill you found in a gist, a repo, or a folder on disk becomes
+ * `<projectDir>/skills/<id>/`, which is the first root the loader scans and the
+ * only one Loom is allowed to write to.
+ *
+ * ## Why so much of this file is refusal
+ *
+ * Both entry points take a string from an HTTP body and turn it into filesystem
+ * writes, so the interesting cases are all the ones that must not happen:
+ *
+ *   - **The id is a path.** `id` is joined onto `<projectDir>/skills/`, so an id
+ *     of `../../.ssh` writes outside the project. It is validated against a
+ *     character class rather than sanitised, because silently rewriting a
+ *     malicious id into a benign one installs a skill under a name the caller
+ *     didn't ask for, and then everything downstream is about the wrong skill.
+ *
+ *   - **The URL is a command.** `installSkillFromGit` runs git. Every argument
+ *     goes through `execFile` with an array — never a shell string — so a URL
+ *     containing `;` or `$(…)` is a URL git will fail to clone, not a command.
+ *     The URL is also checked to be http(s) or ssh git first: git happily
+ *     accepts `ext::sh -c …` and `--upload-pack=…` as "remotes", and those are
+ *     code execution with extra steps.
+ *
+ *   - **An overwrite is silent.** Installing over an existing skill destroys
+ *     whatever the user wrote there. It needs `force`, and the error says which
+ *     id collided so the UI can offer the choice instead of guessing.
+ *
+ * A clone is bounded (90s) and runs with `GIT_TERMINAL_PROMPT=0`: a private repo
+ * must fail as a private repo, not hang a request forever on a credential prompt
+ * that nobody is at a terminal to answer.
+ */
+import { execFile } from "./process.js";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parseSkillMd } from "./skills.js";
+/** A refusal with a reason the UI can show verbatim. Distinct so routes can 400 it. */
+export class SkillInstallError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SkillInstallError";
+    }
+}
+/**
+ * A skill id is a single directory name and nothing else.
+ *
+ * Letters, digits, dot, dash, underscore. No separators (so it cannot escape),
+ * no leading dot (so it cannot be `.` , `..`, or a hidden directory that the
+ * loader would then never list), and a length cap so a 4KB id can't be used to
+ * probe path limits.
+ */
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+function assertSafeId(id) {
+    const clean = String(id ?? "").trim();
+    if (!clean)
+        throw new SkillInstallError("skill id is empty — cannot tell where to install it");
+    if (!ID_RE.test(clean) || clean.includes("..")) {
+        throw new SkillInstallError(`"${clean}" is not a usable skill id — it must be a single directory name of letters, digits, dot, dash or underscore`);
+    }
+    return clean;
+}
+/**
+ * Read and validate the SKILL.md that makes a directory a skill.
+ *
+ * A directory with no SKILL.md is not a skill, and one whose frontmatter has no
+ * `name:` is a skill nothing can refer to — the loader would fall back to the
+ * directory name, which means installing it produces a manifest whose name was
+ * invented here. Both are refused with the path, because "it didn't work" is
+ * useless when you cloned a repo with four candidate folders in it.
+ */
+function readManifest(dir) {
+    const file = path.join(dir, "SKILL.md");
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        throw new SkillInstallError(`no readable SKILL.md in ${dir} — a skill is a directory containing SKILL.md`);
+    }
+    const { name, description } = parseSkillMd(raw);
+    if (!name.trim()) {
+        throw new SkillInstallError(`${file} has no \`name:\` in its frontmatter — a skill needs one to be referred to`);
+    }
+    return { name: name.trim(), description, file };
+}
+/**
+ * Copy a skill directory into the project.
+ *
+ * The whole directory comes across, not just SKILL.md: skills reference scripts
+ * and `references/` files next to them, and a skill installed without its
+ * attachments is a skill whose instructions point at nothing.
+ */
+/**
+ * Author a skill in place: scaffold `skills/<id>/SKILL.md`, validated.
+ *
+ * Skills could be browsed and installed but never written — authoring one
+ * meant knowing the frontmatter convention by heart and hand-building the
+ * directory. The validation is the same reader the roster uses (parseSkillMd),
+ * so a skill this accepts is a skill the loader will actually offer: refusing
+ * to write anything the roster would silently drop is the whole point.
+ */
+export function authorSkill(projectDir, input) {
+    const id = input.id.trim().toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+    if (!id)
+        throw new SkillInstallError("a skill needs an id (letters, digits, dashes)");
+    const name = input.name.trim();
+    if (!name)
+        throw new SkillInstallError("a skill needs a name");
+    const description = input.description.trim();
+    if (!description) {
+        throw new SkillInstallError("a skill needs a description — it's how agents decide when to use it");
+    }
+    const skillsDir = path.join(projectDir, "skills");
+    const dest = path.join(skillsDir, id);
+    if (path.dirname(dest) !== skillsDir) {
+        throw new SkillInstallError(`refusing "${id}" — it resolves outside ${skillsDir}`);
+    }
+    const file = path.join(dest, "SKILL.md");
+    if (fs.existsSync(file)) {
+        throw new SkillInstallError(`"${id}" already exists — edit ${file} instead`);
+    }
+    const md = `---\n` +
+        `name: ${name}\n` +
+        `description: ${description}\n` +
+        `---\n\n` +
+        (input.body?.trim()
+            ? `${input.body.trim()}\n`
+            : `# ${name}\n\nWrite the instructions an agent should follow here.\n\n` +
+                `## When to use\n\n${description}\n\n## Steps\n\n1. …\n`);
+    // Round-trip through the real parser before anything touches disk.
+    const parsed = parseSkillMd(md);
+    if (parsed.name !== name || parsed.description !== description) {
+        throw new SkillInstallError("the generated frontmatter didn't survive the parser — check for YAML-breaking characters");
+    }
+    fs.mkdirSync(dest, { recursive: true });
+    fs.writeFileSync(file, md);
+    return { dir: dest, file };
+}
+export function installSkillFromDir(srcDir, projectDir, opts = {}) {
+    const src = path.resolve(String(srcDir ?? "").trim());
+    if (!src || src === path.parse(src).root) {
+        throw new SkillInstallError("no source directory given");
+    }
+    let stat;
+    try {
+        stat = fs.statSync(src);
+    }
+    catch {
+        throw new SkillInstallError(`${src} does not exist`);
+    }
+    if (!stat.isDirectory())
+        throw new SkillInstallError(`${src} is not a directory`);
+    const id = assertSafeId(opts.id ?? path.basename(src));
+    const { name, description } = readManifest(src);
+    const skillsDir = path.join(projectDir, "skills");
+    const dest = path.join(skillsDir, id);
+    // Belt and braces: assertSafeId already forbids separators, so this can only
+    // fire if that regex is ever loosened. It is cheap and it is the check that
+    // actually protects the filesystem, so it stays.
+    if (path.dirname(dest) !== skillsDir) {
+        throw new SkillInstallError(`refusing to install "${id}" — it resolves outside ${skillsDir}`);
+    }
+    if (path.resolve(dest) === src) {
+        throw new SkillInstallError(`${src} is already this project's "${id}" skill`);
+    }
+    const existed = fs.existsSync(dest);
+    if (existed && !opts.force) {
+        throw new SkillInstallError(`a skill named "${id}" is already installed — pass force to replace it`);
+    }
+    fs.mkdirSync(skillsDir, { recursive: true });
+    if (existed)
+        fs.rmSync(dest, { recursive: true, force: true });
+    fs.cpSync(src, dest, { recursive: true });
+    return {
+        id,
+        name,
+        description,
+        dir: dest,
+        path: path.join(dest, "SKILL.md"),
+        from: "dir",
+        source: src,
+        replaced: existed,
+    };
+}
+// ---------------------------------------------------------------------------
+// git
+// ---------------------------------------------------------------------------
+/**
+ * The remote forms git can be handed safely.
+ *
+ * https/http and ssh (both `ssh://host/path` and the scp-ish `git@host:path`).
+ * Deliberately NOT `file://`, `ext::`, `--upload-pack=`, or a bare local path:
+ * the transport helpers behind those run programs of the remote's choosing, and
+ * a URL field in a web form is not where that decision should be made.
+ */
+const GIT_URL_RE = /^(?:https?:\/\/[^\s]+|ssh:\/\/[^\s]+|[A-Za-z0-9_.-]+@[A-Za-z0-9_.-]+:[^\s]+)$/;
+function assertGitUrl(url) {
+    const clean = String(url ?? "").trim();
+    if (!clean)
+        throw new SkillInstallError("no git URL given");
+    if (clean.startsWith("-")) {
+        // `git clone -- <url>` already stops this, but a URL that looks like a flag
+        // is never a real repository and the error is clearer here.
+        throw new SkillInstallError(`"${clean}" is not a git URL`);
+    }
+    if (!GIT_URL_RE.test(clean)) {
+        throw new SkillInstallError(`"${clean}" is not a git URL — expected https://…, ssh://…, or git@host:owner/repo`);
+    }
+    return clean;
+}
+/** The repository's own name, used as the skill id when SKILL.md sits at the root. */
+function repoName(url) {
+    const tail = url.replace(/\/+$/, "").split(/[/:]/).pop() ?? "";
+    return tail.replace(/\.git$/i, "");
+}
+function runGit(args, cwd, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        execFile("git", args, {
+            cwd,
+            timeout: timeoutMs,
+            maxBuffer: 4 * 1024 * 1024,
+            // No credential prompt, no interactive host-key question: this runs
+            // inside an HTTP handler where there is nobody to answer either.
+            env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_ASKPASS: "echo", GCM_INTERACTIVE: "never" },
+        }, (err, _stdout, stderr) => {
+            if (err) {
+                const detail = String(stderr || err.message).split("\n").find((l) => l.trim())?.trim() ?? "";
+                reject(new SkillInstallError(detail || `git ${args[0]} failed`));
+                return;
+            }
+            resolve();
+        });
+    });
+}
+/**
+ * Clone a repository and install the skill inside it.
+ *
+ * `--depth 1` because history is irrelevant to a directory of markdown, and a
+ * shallow clone of a large skills repo is the difference between a second and a
+ * minute. The SKILL.md is looked for at the repo root first and then one level
+ * down — the two layouts people actually publish ("this repo IS a skill" and
+ * "this repo is a folder of skills"). Deeper than that is ambiguous: a repo with
+ * `a/b/SKILL.md` and `c/d/SKILL.md` has no obvious answer, and picking one is
+ * how you install something the user didn't choose.
+ *
+ * The temp clone is removed on every path, including the failures.
+ */
+export async function installSkillFromGit(url, projectDir, opts = {}) {
+    // "#name" picks one skill out of a repo that holds several; "#all" takes every one.
+    const hash = url.indexOf("#");
+    const pick = hash >= 0 ? url.slice(hash + 1).trim() : "";
+    const remote = assertGitUrl(hash >= 0 ? url.slice(0, hash) : url);
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "loom-skill-"));
+    const checkout = path.join(tmp, "repo");
+    try {
+        await runGit(["clone", "--depth", "1", "--quiet", "--", remote, checkout], tmp, opts.timeoutMs ?? 90_000);
+        const dirs = findSkillDirs(checkout);
+        if (!dirs.length) {
+            throw new SkillInstallError(`no SKILL.md found in ${remote} — looked in the repository root, one level below it, and under skills/`);
+        }
+        const idOf = (d) => (d === checkout ? repoName(remote) : path.basename(d));
+        let chosen;
+        if (pick === "all")
+            chosen = dirs;
+        else if (pick) {
+            const hit = dirs.find((d) => path.basename(d) === pick);
+            if (!hit)
+                throw new SkillInstallError(`no skill "${pick}" in ${remote} — it has: ${dirs.map(idOf).join(", ")}`);
+            chosen = [hit];
+        }
+        else if (dirs.length === 1)
+            chosen = dirs;
+        else {
+            // Several skills and no choice: say so, rather than install whichever sorts first.
+            throw new SkillInstallError(`${remote} holds ${dirs.length} skills: ${dirs.map(idOf).slice(0, 12).join(", ")}${dirs.length > 12 ? ", …" : ""} — add #<name> to the URL to pick one, or #all for every one`);
+        }
+        const results = chosen.map((d) => installSkillFromDir(d, projectDir, { ...opts, id: chosen.length === 1 ? (opts.id ?? idOf(d)) : idOf(d) }));
+        return { ...results[0], from: "git", source: remote, ...(results.length > 1 ? { also: results.slice(1).map((r) => r.id) } : {}) };
+    }
+    finally {
+        try {
+            fs.rmSync(tmp, { recursive: true, force: true });
+        }
+        catch {
+            // A leftover clone in the OS temp dir is not worth failing an install over.
+        }
+    }
+}
+/**
+ * The repo root if it is itself a skill, else the first child directory that is.
+ *
+ * Exported for the tests: the two layouts this handles are the whole of the
+ * git installer's judgement, and a clone is the one part of that path a test
+ * can't reach offline.
+ */
+export function findSkillDir(root) {
+    return findSkillDirs(root)[0] ?? null;
+}
+/**
+ * Every skill in a checkout: the root if it is one; else each child directory
+ * that is; else each one under skills/ (and .claude/skills/) — the layouts
+ * people publish.
+ */
+export function findSkillDirs(root) {
+    if (fs.existsSync(path.join(root, "SKILL.md")))
+        return [root];
+    const kids = (dir) => {
+        try {
+            return fs
+                .readdirSync(dir, { withFileTypes: true })
+                .filter((d) => d.isDirectory() && !d.name.startsWith("."))
+                .map((d) => path.join(dir, d.name))
+                .filter((d) => fs.existsSync(path.join(d, "SKILL.md")))
+                .sort();
+        }
+        catch {
+            return [];
+        }
+    };
+    const top = kids(root);
+    if (top.length)
+        return top;
+    return [...kids(path.join(root, "skills")), ...kids(path.join(root, ".claude", "skills"))];
+}
+//# sourceMappingURL=skill-install.js.map