npm - @liebstoeckel/cli - Versions diffs - 0.3.7 - Mend

@liebstoeckel/cli 0.3.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/LICENSE +373 -0
package/README.md +74 -0
package/package.json +60 -0
package/skill/AGENTS.md +18 -0
package/skill/SKILL.md +144 -0
package/skill/references/authoring.md +81 -0
package/skill/references/build-plugins.md +116 -0
package/skill/references/components.md +107 -0
package/skill/references/editing.md +78 -0
package/skill/references/plugins.md +121 -0
package/skill/references/troubleshooting.md +39 -0
package/src/add.ts +369 -0
package/src/build.ts +354 -0
package/src/cli.ts +78 -0
package/src/cloud.ts +570 -0
package/src/creds.ts +31 -0
package/src/new.ts +310 -0
package/src/registry.ts +124 -0
package/src/skill.ts +167 -0
package/src/targeting.ts +8 -0
package/src/trust.ts +73 -0
package/src/update.ts +148 -0

package/src/new.ts ADDED Viewed

@@ -0,0 +1,310 @@
+import { defineCommand } from "citty";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export const VALID_NAME = /^[a-z0-9][a-z0-9-]*$/;
+const titleCase = (name: string) => name.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+export interface ScaffoldOptions {
+  brand?: string;
+  /** parent directory for the new deck (default: the current working directory) */
+  dir?: string;
+  /** opt out of auto-applying the logged-in org's default brand (ADR 0059) */
+  noOrgBrand?: boolean;
+}
+/** Pure: the file map for a new minimal deck (deck-relative path → contents).
+ *  Kept as plain templates so a richer template library can grow from here. */
+/** Per-dependency version ranges for the scaffolded deck (ADR 0051). Independently
+ *  versioned, so each is resolved from its OWN package. */
+export interface DeckDeps {
+  engine?: string;
+  theme?: string;
+  thumbnails?: string;
+}
+export function deckFiles(
+  name: string,
+  brand = "liebstoeckel",
+  deps: DeckDeps = {},
+  orgBrand?: { name: string; source: string; dependencies?: string[] },
+): Record<string, string> {
+  const range = (k: keyof DeckDeps) => deps[k] ?? "workspace:*";
+  const title = titleCase(name);
+  // When `new` is run logged-in, the org's default brand (ADR 0059) is baked in:
+  // a local brands/<name>.ts wired via <Present brandThemes>, self-contained.
+  const brandId = orgBrand?.name ?? brand;
+  const brandImport = orgBrand ? `import orgBrand from "./brands/${orgBrand.name}";\n` : "";
+  const brandThemesProp = orgBrand ? " brandThemes={[orgBrand]}" : "";
+  // The default brand's catalog fonts (ADR 0074) are @fontsource packages the baked
+  // brands/<name>.ts imports, add them so the deck's `bun install` fetches the
+  // webfont (built decks inline it). `latest` (a third-party dist-tag) since the CLI
+  // can't resolve their version like the framework deps; the lockfile pins on install.
+  const fontDeps = Object.fromEntries((orgBrand?.dependencies ?? []).map((p) => [p, "latest"]));
+  const pkg = {
+    // A scaffolded deck is the user's own private project, a BARE name, not the
+    // framework's `@liebstoeckel/` npm scope (ADR 0054). Only the framework
+    // *dependencies* below keep that scope.
+    name,
+    version: "0.0.0",
+    private: true,
+    type: "module",
+    // Allowlist of what `bun pm pack` ships, and therefore what `liebstoeckel build`
+    // embeds as recoverable source and `eject` restores (ADR 0039). Deny-by-default:
+    // a stray .env / secret is never packed because it isn't listed here. bunfig.toml
+    // MUST stay listed, pack default-ignores it, and the ejected deck needs it for dev.
+    // Add new top-level source dirs here as the deck grows (the build warns if you forget).
+    files: [
+      "index.html",
+      "main.tsx",
+      "server.ts",
+      "build.ts",
+      "bunfig.toml",
+      "slides",
+      "elements",
+      "components",
+      "charts",
+      "brands",
+      "assets",
+      "public",
+    ],
+    scripts: { dev: "bun --hot ./server.ts", build: "bun run build.ts" },
+    dependencies: {
+      "@liebstoeckel/engine": range("engine"),
+      "@liebstoeckel/theme": range("theme"),
+      ...fontDeps,
+    },
+    devDependencies: { "@liebstoeckel/thumbnails": range("thumbnails") },
+  };
+  return {
+    "package.json": JSON.stringify(pkg, null, 2) + "\n",
+    // Defense-in-depth for decks used outside the monorepo: keep build output and
+    // secrets out of version control (and the `files` allowlist above keeps them out
+    // of the packed/embedded source regardless).
+    ".gitignore": `node_modules/
+dist/
+*.tgz
+.env
+.env.*
+`,
+    "index.html": `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link
+      rel="icon"
+      href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='7' fill='%23121212'/%3E%3Crect x='7' y='9' width='18' height='13' rx='2' fill='none' stroke='%23c8a96a' stroke-width='2'/%3E%3C/svg%3E"
+    />
+    <title>${title}</title>
+  </head>
+  <body data-brand="${brandId}">
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>
+`,
+    "bunfig.toml": `# Plugins for the HMR dev server (Bun.serve HTML routes). The build path uses
+# Bun.build()'s plugins array in build.ts instead.
+[serve.static]
+plugins = ["bun-plugin-tailwind", "@liebstoeckel/engine/mdx-plugin", "@liebstoeckel/engine/visx-esm-plugin"]
+`,
+    "server.ts": `import index from "./index.html";
+// Dev server with frontend HMR + React Fast Refresh.
+const server = Bun.serve({
+  routes: { "/": index },
+  development: { hmr: true, console: true },
+  hostname: "0.0.0.0",
+  port: Number(process.env.PORT) || 3000,
+});
+console.log(\`▶  http://localhost:\${server.port}\`);
+`,
+    "build.ts": `import { buildDeck } from "@liebstoeckel/thumbnails/build";
+// Single self-contained .html + slide thumbnails (skip with LIEBSTOECKEL_NO_THUMBS=1).
+await buildDeck({ entry: "./index.html", outdir: "./dist" });
+`,
+    "main.tsx": `import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { Present } from "@liebstoeckel/engine";
+import "@liebstoeckel/theme/styles.css";
+${brandImport}
+import Intro from "./slides/01-intro";
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <Present title="${title}" brands={["${brandId}"]}${brandThemesProp} slides={[Intro]} />
+  </StrictMode>,
+);
+`,
+    "slides/01-intro.tsx": `import { Step } from "@liebstoeckel/engine";
+export default function Intro() {
+  return (
+    <div className="w-full">
+      <div className="mb-5 flex items-center gap-3 font-mono text-sm uppercase tracking-[0.35em] text-accent">
+        <span className="h-px w-8 bg-accent" />
+        liebstoeckel
+      </div>
+      <h1 className="font-heading text-[88px] font-semibold leading-[0.95] tracking-[-0.03em] text-text">
+        ${title}
+      </h1>
+      <div className="mt-10 space-y-4 font-body text-2xl text-muted">
+        <Step>▹ Edit slides/01-intro.tsx</Step>
+        <Step>▹ Add slides and wire them up in main.tsx</Step>
+        <Step>▹ bun run build → one self-contained .html</Step>
+      </div>
+    </div>
+  );
+}
+`,
+    // Org default brand baked in as owned source (ADR 0059).
+    ...(orgBrand ? { [`brands/${orgBrand.name}.ts`]: orgBrand.source } : {}),
+  };
+}
+/** Version string from the nearest package.json above a resolved module path. */
+function nearestPkgVersion(entry: string): string | null {
+  let dir = dirname(entry.startsWith("file://") ? fileURLToPath(entry) : entry);
+  for (let i = 0; i < 6 && dir !== dirname(dir); i++) {
+    const pj = join(dir, "package.json");
+    if (existsSync(pj)) {
+      try {
+        return (JSON.parse(readFileSync(pj, "utf8")) as { version?: string }).version ?? null;
+      } catch {
+        return null;
+      }
+    }
+    dir = dirname(dir);
+  }
+  return null;
+}
+const caret = (v: string | null | undefined) => (v && v !== "0.0.0" ? `^${v}` : null);
+/** The `^<version>` range to scaffold for a framework dep, read from that dep's
+ *  OWN resolved package (independently versioned, ADR 0081).
+ *
+ *  Invariant: every scaffolded dependency MUST be a direct dependency of
+ *  `@liebstoeckel/cli`, so it is installed alongside the CLI and resolvable both
+ *  in-repo and standalone. We rely on that and **fail loud** if it doesn't hold.
+ *  The old fallback to the CLI's *own* version was only correct under lockstep;
+ *  with graph-driven versioning it would silently stamp a wrong, lockstep-shaped
+ *  pin onto a package that no longer shares the CLI's version, a far worse failure
+ *  than a clear error. */
+function depRange(name: string): string {
+  let resolved: string;
+  try {
+    resolved = import.meta.resolveSync(name);
+  } catch (err) {
+    throw new Error(
+      `scaffold: cannot resolve ${name} to read its version. Every scaffolded ` +
+        `dependency must be a direct dependency of @liebstoeckel/cli so it is ` +
+        `installed alongside the CLI (ADR 0081). Original error: ${(err as Error).message}`,
+    );
+  }
+  const version = nearestPkgVersion(resolved);
+  const range = caret(version);
+  if (!range) {
+    throw new Error(
+      `scaffold: resolved ${name} but its package.json has no usable version ` +
+        `(found ${version ?? "none"}); cannot emit a real range for it (ADR 0081).`,
+    );
+  }
+  return range;
+}
+/** Write a new minimal deck to disk. Throws on an invalid name or existing dir. */
+export async function scaffold(
+  name: string,
+  opts: ScaffoldOptions = {},
+): Promise<{ dir: string; files: string[]; brand: string }> {
+  if (!VALID_NAME.test(name)) {
+    throw new Error(`invalid deck name "${name}", use lower-case letters, digits and hyphens`);
+  }
+  const brand = opts.brand ?? "liebstoeckel";
+  // Unless a brand was named explicitly (or opted out), bake the logged-in org's
+  // default brand so new decks are on-brand instantly (ADR 0059). Best effort, // never blocks scaffolding when offline / not logged in.
+  const orgBrand = !opts.brand && !opts.noOrgBrand ? await (await import("./cloud")).fetchDefaultBrand() : null;
+  // The deck materializes in the current directory as ./<name> (least surprising).
+  // Override the parent with --dir (e.g. --dir presentations).
+  const root = opts.dir ? resolve(opts.dir) : process.cwd();
+  const dir = join(root, name);
+  if (existsSync(dir)) throw new Error(`${dir} already exists`);
+  const files = deckFiles(
+    name,
+    brand,
+    {
+      engine: depRange("@liebstoeckel/engine"),
+      theme: depRange("@liebstoeckel/theme"),
+      thumbnails: depRange("@liebstoeckel/thumbnails"),
+    },
+    orgBrand ?? undefined,
+  );
+  for (const [rel, content] of Object.entries(files)) {
+    await Bun.write(join(dir, rel), content);
+  }
+  // A deck scaffolded here is authored by this user — trust it so building it never
+  // trips the untrusted-deck confirmation gate (see trust.ts).
+  await (await import("./trust")).trustDeck(dir);
+  return { dir, files: Object.keys(files), brand: orgBrand?.name ?? brand };
+}
+export const newCommand = defineCommand({
+  meta: {
+    name: "new",
+    description: "scaffold a new deck as ./<name> (or under --dir)",
+  },
+  args: {
+    name: {
+      type: "positional",
+      required: false,
+      description: "deck name (lower-case letters, digits, hyphens)",
+      valueHint: "name",
+    },
+    brand: { type: "string", description: "brand to apply", valueHint: "brand" },
+    dir: { type: "string", description: "parent directory for the new deck", valueHint: "parent" },
+    "org-brand": {
+      type: "boolean",
+      default: true,
+      description: "apply the logged-in org's default brand",
+      negativeDescription: "do not apply the org default brand",
+    },
+  },
+  async run({ args }) {
+    const name = args.name;
+    if (!name) {
+      console.error("usage: liebstoeckel new <name> [--brand <brand>] [--dir <parent>] [--no-org-brand]");
+      process.exit(1);
+    }
+    try {
+      const { dir, files } = await scaffold(name, {
+        brand: args.brand,
+        dir: args.dir,
+        noOrgBrand: args.orgBrand === false,
+      });
+      console.log(`\n✓ created deck "${name}" → ${dir}\n`);
+      for (const f of files) console.log(`   ${f}`);
+      console.log(`\n   next:`);
+      console.log(`     bun install`);
+      console.log(`     liebstoeckel live ${dir}      # or: bun --cwd ${dir} run dev\n`);
+    } catch (e) {
+      console.error(`✕ ${(e as Error).message}`);
+      process.exit(1);
+    }
+  },
+});

package/src/registry.ts ADDED Viewed

@@ -0,0 +1,124 @@
+import { defineCommand } from "citty";
+import { join } from "node:path";
+import { REGISTRY_ROOT } from "@liebstoeckel/registry";
+import { validateItem, type RegistryIndex, type RegistryItem } from "@liebstoeckel/registry/schema";
+/**
+ * `liebstoeckel registry list|view`, agent-readable discovery over the bundled
+ * default registry (ADR 0045). Output is JSON when `--json` is passed OR when stdout
+ * is not a TTY (so an agent piping the command always gets structured data), and a
+ * compact human view on an interactive terminal.
+ *
+ * Third-party / namespaced registries (ADR 0041) are not resolved here yet, this
+ * reads the bundled `@liebstoeckel` registry directly.
+ */
+// JSON when asked, or when piped (an agent), pretty only on an interactive TTY (ADR 0045).
+const wantsJson = (json: boolean | undefined): boolean => !!json || !process.stdout.isTTY;
+const readIndex = (): Promise<RegistryIndex> =>
+  Bun.file(join(REGISTRY_ROOT, "registry.json")).json() as Promise<RegistryIndex>;
+async function readItem(name: string): Promise<RegistryItem> {
+  const f = Bun.file(join(REGISTRY_ROOT, "items", `${name}.json`));
+  if (!(await f.exists())) throw new Error(`registry item "${name}" not found, try \`liebstoeckel registry list\``);
+  const item = (await f.json()) as RegistryItem;
+  validateItem(item);
+  return item;
+}
+/** A catalog row enriched with the headline agent-facing meta, so `list --json` gives
+ *  the agent the whole catalog + data shapes in a single call (fewer round-trips). */
+interface CatalogRow {
+  name: string;
+  type: string;
+  description?: string;
+  exports?: string;
+  dataShape?: string;
+}
+async function catalog(): Promise<CatalogRow[]> {
+  const index = await readIndex();
+  return Promise.all(
+    index.items.map(async (i) => {
+      const item = await readItem(i.name);
+      return {
+        name: i.name,
+        type: i.type.replace(/^registry:/, ""),
+        description: i.description,
+        exports: item.meta?.exports,
+        dataShape: item.meta?.dataShape,
+      };
+    }),
+  );
+}
+function printList(rows: CatalogRow[]): void {
+  console.log(`\n${rows.length} registry items (\`liebstoeckel add <name>\` to scaffold):\n`);
+  const w = Math.max(...rows.map((r) => r.name.length));
+  for (const r of rows) {
+    console.log(`  ${r.name.padEnd(w)}  ${r.type.padEnd(9)} ${r.dataShape ? `data: ${r.dataShape}` : r.description ?? ""}`);
+  }
+  console.log(`\n  view one: liebstoeckel registry view <name>\n`);
+}
+function printItem(item: RegistryItem): void {
+  const m = item.meta ?? {};
+  console.log(`\n${item.name}  (${item.type.replace(/^registry:/, "")})`);
+  if (item.description) console.log(`  ${item.description}`);
+  if (m.exports) console.log(`\n  exports:    ${m.exports}`);
+  if (m.props) console.log(`  props:      ${m.props}`);
+  if (m.dataShape) console.log(`  data:       ${m.dataShape}`);
+  if (m.example) console.log(`  example:    ${m.example}`);
+  if (item.dependencies?.length) console.log(`\n  npm deps:   ${item.dependencies.join(", ")}`);
+  if (item.registryDependencies?.length) console.log(`  also adds:  ${item.registryDependencies.join(", ")}`);
+  console.log(`\n  scaffold:   liebstoeckel add ${item.name}\n`);
+}
+const registryListCommand = defineCommand({
+  meta: { name: "list", description: "list the chart/component registry" },
+  args: { json: { type: "boolean", description: "machine-readable JSON (default when piped)" } },
+  async run({ args }) {
+    const json = wantsJson(args.json);
+    try {
+      const rows = await catalog();
+      if (json) console.log(JSON.stringify(rows, null, 2));
+      else printList(rows);
+    } catch (e) {
+      if (json) console.log(JSON.stringify({ error: (e as Error).message }));
+      else console.error(`✕ ${(e as Error).message}`);
+      process.exit(1);
+    }
+  },
+});
+const registryViewCommand = defineCommand({
+  meta: { name: "view", description: "show one registry item's details" },
+  args: {
+    name: { type: "positional", required: false, description: "registry item name", valueHint: "name" },
+    json: { type: "boolean", description: "machine-readable JSON (default when piped)" },
+  },
+  async run({ args }) {
+    const json = wantsJson(args.json);
+    if (!args.name) {
+      console.error("usage: liebstoeckel registry view <name> [--json]");
+      process.exit(1);
+    }
+    try {
+      const item = await readItem(args.name);
+      if (json) console.log(JSON.stringify(item, null, 2));
+      else printItem(item);
+    } catch (e) {
+      if (json) console.log(JSON.stringify({ error: (e as Error).message }));
+      else console.error(`✕ ${(e as Error).message}`);
+      process.exit(1);
+    }
+  },
+});
+/** `liebstoeckel registry list|view`, agent-readable discovery (ADR 0045). */
+export const registryCommand = defineCommand({
+  meta: { name: "registry", description: "browse the chart/component registry (JSON for agents)" },
+  subCommands: { list: registryListCommand, view: registryViewCommand },
+  default: "list",
+});

package/src/skill.ts ADDED Viewed

@@ -0,0 +1,167 @@
+import { defineCommand } from "citty";
+import { fileURLToPath } from "node:url";
+import { existsSync, readdirSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+/**
+ * `liebstoeckel skill install`, materialize the bundled `liebstoeckel-deck` Skill
+ * into a deck for whichever agents the user runs (ADR 0044). One canonical source
+ * (shipped in this package, version-pinned to the CLI) is placed at each agent's
+ * expected path, and a universal `AGENTS.md` block is written as the fallback for
+ * agents with weak or no skill support.
+ */
+const SKILL_NAME = "liebstoeckel-deck";
+// Canonical source: packages/cli/skill/ (this file is packages/cli/src/skill.ts).
+const SKILL_SRC = fileURLToPath(new URL("../skill", import.meta.url));
+const PKG_JSON = fileURLToPath(new URL("../package.json", import.meta.url));
+type Target = "claude" | "codex" | "cursor" | "gemini";
+const ALL_TARGETS: Target[] = ["claude", "codex", "cursor", "gemini"];
+// Where each agent looks for a skill folder, relative to the deck root.
+export const SKILL_DIR: Record<Target, string> = {
+  claude: join(".claude", "skills", SKILL_NAME),
+  codex: join(".agents", "skills", SKILL_NAME), // also read by Gemini's shared path
+  cursor: join(".cursor", "skills", SKILL_NAME),
+  gemini: join(".gemini", "skills", SKILL_NAME),
+};
+export async function cliVersion(): Promise<string> {
+  try {
+    return ((await Bun.file(PKG_JSON).json()) as { version?: string }).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+/** The skill's payload files (everything under skill/ except the AGENTS.md template). */
+function skillFiles(): string[] {
+  const out = ["SKILL.md"];
+  const refs = join(SKILL_SRC, "references");
+  if (existsSync(refs)) for (const f of readdirSync(refs)) out.push(join("references", f));
+  return out;
+}
+/** Copy the skill into one destination, stamping the CLI version into SKILL.md. */
+async function writeSkill(destRoot: string, version: string): Promise<void> {
+  for (const rel of skillFiles()) {
+    let content = await Bun.file(join(SKILL_SRC, rel)).text();
+    if (rel === "SKILL.md") content = content.replace(/(\n\s*version:\s*).*/, `$1${version}`);
+    const dest = join(destRoot, rel);
+    await mkdir(dirname(dest), { recursive: true });
+    await Bun.write(dest, content);
+  }
+}
+const AGENTS_BLOCK_RE = /<!-- liebstoeckel:start -->[\s\S]*?<!-- liebstoeckel:end -->/;
+/** Merge the managed liebstoeckel block into an AGENTS.md body: replace it in place
+ *  if present (idempotent), else append it. Pure, the unit-test anchor. */
+export function mergeAgentsBlock(existing: string, block: string): string {
+  const b = block.trim();
+  if (AGENTS_BLOCK_RE.test(existing)) return existing.replace(AGENTS_BLOCK_RE, b);
+  return (existing.trim() ? `${existing.trim()}\n\n` : "") + b + "\n";
+}
+/** Write or replace the managed liebstoeckel block in the deck's AGENTS.md. */
+async function writeAgentsBlock(deckDir: string): Promise<void> {
+  const block = await Bun.file(join(SKILL_SRC, "AGENTS.md")).text();
+  const path = join(deckDir, "AGENTS.md");
+  const existing = existsSync(path) ? await Bun.file(path).text() : "";
+  await Bun.write(path, mergeAgentsBlock(existing, block));
+}
+/** A small Cursor rule pointing at the placed skill (Cursor reads `.cursor/rules/*.mdc`). */
+async function writeCursorRule(deckDir: string): Promise<void> {
+  const mdc = `---
+description: Use the liebstoeckel-deck skill to create or edit presentation decks (liebstoeckel CLI).
+alwaysApply: false
+---
+When working on liebstoeckel presentation decks, follow ${join(".cursor", "skills", SKILL_NAME, "SKILL.md")}.
+Discover components with \`liebstoeckel registry list --json\`; validate with \`liebstoeckel build --check\`.
+`;
+  const dest = join(deckDir, ".cursor", "rules", "liebstoeckel.mdc");
+  await mkdir(dirname(dest), { recursive: true });
+  await Bun.write(dest, mdc);
+}
+async function applySkill(sub: "install" | "update", deckDir: string, targetArg: string | undefined): Promise<void> {
+  let targets: Target[];
+  if (sub === "update") {
+    // Refresh whatever is already installed (the AGENTS.md block is always
+    // rewritten); installing NEW agent paths stays `install`'s job.
+    targets = ALL_TARGETS.filter((t) => existsSync(join(deckDir, SKILL_DIR[t])));
+    if (targets.length === 0 && !existsSync(join(deckDir, "AGENTS.md"))) {
+      console.error(`✕ no liebstoeckel skill installed in ${deckDir}, run: liebstoeckel skill install`);
+      process.exit(1);
+    }
+  } else {
+    const tArg = targetArg ?? "all";
+    targets =
+      !tArg || tArg === "all" ? ALL_TARGETS : (tArg.split(",").filter((t): t is Target => (ALL_TARGETS as string[]).includes(t)));
+    if (targets.length === 0) {
+      console.error(`unknown --target "${tArg}", use one or more of: ${ALL_TARGETS.join(", ")}, or all`);
+      process.exit(1);
+    }
+  }
+  const version = await cliVersion();
+  const written: string[] = [];
+  try {
+    // de-dupe destination dirs (some agents share a path)
+    const seen = new Set<string>();
+    for (const t of targets) {
+      const destRoot = join(deckDir, SKILL_DIR[t]);
+      if (!seen.has(destRoot)) {
+        await writeSkill(destRoot, version);
+        seen.add(destRoot);
+        written.push(SKILL_DIR[t] + "/");
+      }
+      if (t === "cursor") {
+        await writeCursorRule(deckDir);
+        written.push(join(".cursor", "rules", "liebstoeckel.mdc"));
+      }
+    }
+    // AGENTS.md is the universal fallback, always write it
+    await writeAgentsBlock(deckDir);
+    written.push("AGENTS.md");
+    console.log(`\n✓ ${sub === "update" ? "updated" : "installed"} the liebstoeckel-deck skill (v${version}) → ${deckDir}\n`);
+    for (const w of written) console.log(`   ${w}`);
+    console.log(`\n   targets: ${targets.join(", ")}\n`);
+  } catch (e) {
+    console.error(`✕ ${(e as Error).message}`);
+    process.exit(1);
+  }
+}
+const skillInstallCommand = defineCommand({
+  meta: { name: "install", description: "install the agent skill (SKILL.md + AGENTS.md) into a deck" },
+  args: {
+    target: {
+      type: "string",
+      default: "all",
+      description: "agents to target: claude, codex, cursor, gemini, all (comma-separated)",
+      valueHint: "claude|codex|cursor|gemini|all",
+    },
+    dir: { type: "string", description: "target deck directory (default: cwd)", valueHint: "deck" },
+  },
+  run: ({ args }) => applySkill("install", args.dir ?? ".", args.target),
+});
+const skillUpdateCommand = defineCommand({
+  meta: { name: "update", description: "refresh the installed agent skill to the running CLI version" },
+  args: {
+    dir: { type: "string", description: "target deck directory (default: cwd)", valueHint: "deck" },
+  },
+  run: ({ args }) => applySkill("update", args.dir ?? ".", undefined),
+});
+/** `liebstoeckel skill install|update`, manage the bundled deck-authoring Skill. */
+export const skillCommand = defineCommand({
+  meta: { name: "skill", description: "install/refresh the agent skill for deck authoring" },
+  subCommands: { install: skillInstallCommand, update: skillUpdateCommand },
+});

package/src/targeting.ts ADDED Viewed

@@ -0,0 +1,8 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+/** Does this token name a deck the CLI should act on?, a `.html` path, or any
+ *  existing path. Used by the `liebstoeckel <deck>` → `live` shorthand and by
+ *  `licenses` (which accepts a built `.html` or a source dir). */
+export const looksLikeDeck = (s: string | undefined): boolean =>
+  !!s && (/\.html?$/i.test(s) || existsSync(resolve(s)));

package/src/trust.ts ADDED Viewed

@@ -0,0 +1,73 @@
+// Build-time trust gate. A liebstoeckel deck is *code*: building it runs the deck's
+// build-time modules (Bun macros such as the animated-code macro, build plugins) in this
+// process with full filesystem and network access. Building a deck you did not write —
+// cloned, downloaded, scaffolded by an agent — is therefore arbitrary code execution on
+// your machine. This gate requires an explicit one-time confirmation before the first
+// build of an unfamiliar deck.
+//
+// The trust ledger lives in the user config dir (NOT inside the deck), keyed by absolute
+// path, so a shared/cloned deck can never ship a forged "trusted" marker of its own. A
+// deck scaffolded here via `liebstoeckel new` is recorded as trusted automatically, so an
+// author is never prompted for decks they created on this machine.
+import { mkdir } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { CONFIG_DIR } from "./creds";
+/** Ledger path. `LIEBSTOECKEL_TRUST_FILE` overrides it (a test seam; resolved per call
+ *  so tests can point at a temp file without touching the real user config). */
+function trustFile(): string {
+  return process.env.LIEBSTOECKEL_TRUST_FILE || join(CONFIG_DIR, "trusted-decks.json");
+}
+interface TrustLedger {
+  paths: string[];
+}
+async function readLedger(): Promise<TrustLedger> {
+  try {
+    const j = JSON.parse(await Bun.file(trustFile()).text()) as Partial<TrustLedger>;
+    return { paths: Array.isArray(j.paths) ? j.paths : [] };
+  } catch {
+    return { paths: [] };
+  }
+}
+/** Record `dir` as a deck the author trusts to execute its build-time code here. */
+export async function trustDeck(dir: string): Promise<void> {
+  const abs = resolve(dir);
+  const led = await readLedger();
+  if (led.paths.includes(abs)) return;
+  led.paths.push(abs);
+  const file = trustFile();
+  await mkdir(dirname(file), { recursive: true });
+  await Bun.write(file, JSON.stringify(led, null, 2));
+}
+/** Has `dir` been trusted before (or scaffolded here)? */
+export async function isDeckTrusted(dir: string): Promise<boolean> {
+  return (await readLedger()).paths.includes(resolve(dir));
+}
+export interface TrustGateOptions {
+  /** Pre-approved out of band (`--trust` flag or `LIEBSTOECKEL_TRUST_BUILD=1`). */
+  preapproved?: boolean;
+  /** Interactive confirm; returns true to trust. Injected so the gate stays testable.
+   *  Omit (e.g. non-TTY) to refuse rather than prompt. */
+  confirm?: (dir: string) => boolean;
+}
+/** Decide whether a build of `dir` may proceed, remembering a yes. Returns true to build,
+ *  false to abort. Trusted-or-scaffolded decks pass silently; an unfamiliar deck needs
+ *  `preapproved` or a `confirm` that returns true. */
+export async function ensureBuildTrust(dir: string, opts: TrustGateOptions): Promise<boolean> {
+  if (await isDeckTrusted(dir)) return true;
+  if (opts.preapproved) {
+    await trustDeck(dir);
+    return true;
+  }
+  if (opts.confirm && opts.confirm(resolve(dir))) {
+    await trustDeck(dir);
+    return true;
+  }
+  return false;
+}