@craftrpgs/cli 0.1.2 → 0.1.4

package/README.md

@@ -7,7 +7,8 @@ back — git-style, with three-way sync and conflict handling.
 ```sh
 npm install -g @craftrpgs/cli
 craft login
-craft create "My World"
+craft systems                                # browse published game systems
+craft create "My World" --system "Ashes RPG" # build on one (--blank starts from scratch)
 cd my-world
 # edit files, then:
 craft status
@@ -28,9 +29,10 @@ know how to work with the project the moment you open it.
 | Command | What it does |
 |---|---|
 | `craft login` / `logout` | Browser sign-in (credentials stored per server) |
-| `craft create <name>` | Create a new project and clone it |
+| `craft create <name>` | Create a new project and clone it (`--system <id\|name>` builds on a published system; `--blank` starts from scratch) |
 | `craft clone <idOrUrl>` | Download a project as a local workspace |
 | `craft projects` | List projects your account owns |
+| `craft systems [query]` | Browse published game systems to build on (featured + community) |
 | `craft status` / `diff` | Show local changes (add `--remote` for drift) |
 | `craft check` | Validate the workspace locally (the same checks the server runs at push) |
 | `craft project-completeness` | Worldbuilding completeness report (recommendations; always exits 0) |

package/dist/bin.js

@@ -27454,6 +27454,7 @@ function cliPushResponseForOpsSchema(ops) {
     }
   });
 }
+var MAX_IMPORT_ZIP_BYTES = 50 * 1024 * 1024;
 var cliImportOptionsSchema = exports_external.object({
   dryRun: exports_external.boolean().default(false),
   overwrite: exports_external.boolean().default(false),
@@ -27608,8 +27609,11 @@ var cliImageVariationsResponseSchema = exports_external.object({
 var cliCreateProjectRequestSchema = exports_external.object({
   name: exports_external.string().min(1).max(200),
   description: exports_external.string().max(2000).optional(),
-  seedStarterContent: exports_external.boolean().optional()
-}).strict();
+  seedStarterContent: exports_external.boolean().optional(),
+  systemProjectId: uuidSchema.optional()
+}).strict().refine((value) => !(value.systemProjectId && value.seedStarterContent !== undefined), {
+  message: "seedStarterContent does not apply when creating from a system — the system supplies the content"
+});
 var cliCreateProjectResponseSchema = exports_external.object({
   projectId: uuidSchema,
   containerId: uuidSchema
@@ -27625,6 +27629,26 @@ var cliProjectSummarySchema = exports_external.object({
 var cliProjectsListResponseSchema = exports_external.object({
   projects: exports_external.array(cliProjectSummarySchema)
 }).strict();
+var cliSystemSummarySchema = exports_external.object({
+  projectId: uuidSchema,
+  name: exports_external.string(),
+  description: exports_external.string().nullable(),
+  gameSystemName: exports_external.string().nullable(),
+  ownerUsername: exports_external.string().nullable(),
+  official: exports_external.boolean(),
+  featured: exports_external.boolean(),
+  tags: exports_external.array(exports_external.string()),
+  fileTypeNames: exports_external.array(exports_external.string()),
+  fileCount: exports_external.number().int().nonnegative().nullable(),
+  likeCount: exports_external.number().int().nonnegative(),
+  cloneCount: exports_external.number().int().nonnegative(),
+  publishedAt: exports_external.string().nullable()
+}).strict();
+var cliSystemsResponseSchema = exports_external.object({
+  featured: exports_external.array(cliSystemSummarySchema),
+  community: exports_external.array(cliSystemSummarySchema),
+  communityNextCursor: exports_external.string().nullable()
+}).strict();
 var cliFileVersionEntrySchema = exports_external.object({
   versionId: uuidSchema,
   createdAt: exports_external.string(),
@@ -41858,7 +41882,7 @@ function describeRemoteSource(resolved) {
 // package.json
 var package_default = {
   name: "@craftrpgs/cli",
-  version: "0.1.2",
+  version: "0.1.4",
   description: "Sync Craft projects with a local folder — clone, edit with any coding agent, push back.",
   license: "UNLICENSED",
   homepage: "https://craftrpgs.com",
@@ -42043,6 +42067,30 @@ function createCliClient({
       }
       return parseJson(response, cliCreateProjectResponseSchema, "create project");
     },
+    async fetchSystems({ q, tags, cursor, limit } = {}) {
+      const params = new URLSearchParams;
+      if (q) {
+        params.set("q", q);
+      }
+      for (const tag of tags ?? []) {
+        params.append("tags", tag);
+      }
+      if (cursor) {
+        params.set("cursor", cursor);
+      }
+      if (limit !== undefined) {
+        params.set("limit", String(limit));
+      }
+      const query = params.size > 0 ? `?${params.toString()}` : "";
+      const response = await request(`/api/projects/cli/systems${query}`);
+      if (response.status === 404) {
+        return null;
+      }
+      if (!response.ok) {
+        throw new CliError(`Listing systems failed: ${await readErrorMessage(response)}`, 1);
+      }
+      return parseJson(response, cliSystemsResponseSchema, "systems");
+    },
     async listProjects() {
       const response = await request("/api/projects/cli/list");
       if (!response.ok) {
@@ -42280,6 +42328,36 @@ async function defaultCloneDir(base) {
   }
   throw new CliError(`Could not find a free directory name near ${base}; pass [dir] explicitly.`, 2);
 }
+async function assertUsableCloneTarget({
+  targetDir,
+  zipFilePaths
+}) {
+  if (!existsSync4(targetDir)) {
+    return;
+  }
+  const existing = await readdir3(targetDir);
+  const visible = existing.filter((name) => !shouldSkipWorkspaceName(name));
+  const collisions = zipFilePaths.filter((relative2) => {
+    try {
+      return existsSync4(joinUnderWorkspaceRoot(targetDir, relative2));
+    } catch {
+      return false;
+    }
+  });
+  if (visible.length === 0 && collisions.length === 0) {
+    return;
+  }
+  throw new CliError([
+    `Refusing to clone into ${targetDir}:`,
+    ...visible.map((name) => `  ${name} — pre-existing and would be mixed into the new workspace`),
+    ...collisions.map((relative2) => `  ${relative2} — the project snapshot would overwrite it`),
+    "Entries the workspace scanner ignores (.git/, .gitignore, other dotfiles) may pre-exist; move the listed items or pick a different [dir]."
+  ].join(`
+`), 2);
+}
+function nextStepHint(targetDir) {
+  return targetDir === process.cwd() ? "Next: run `craft status`." : "Next: cd in and run `craft status`.";
+}
 async function downloadAndUnpackSnapshot({
   client,
   projectId,
@@ -42290,12 +42368,8 @@ async function downloadAndUnpackSnapshot({
   const paths = Object.keys(entries);
   const rootDir = zipRootDir(paths);
   const targetDir = dirArg ? resolve4(dirArg) : await defaultCloneDir(resolve4(rootDir));
-  if (existsSync4(targetDir)) {
-    const existing = await readdir3(targetDir);
-    if (existing.length > 0) {
-      throw new CliError(`Refusing to clone into non-empty directory ${targetDir}`, 2);
-    }
-  }
+  const zipFilePaths = paths.filter((path) => !path.endsWith("/")).map((path) => path.slice(rootDir.length + 1)).filter((relative2) => relative2 !== "");
+  await assertUsableCloneTarget({ targetDir, zipFilePaths });
   await mkdir3(targetDir, { recursive: true });
   let fileCount = 0;
   for (const [path, bytes] of Object.entries(entries)) {
@@ -42362,12 +42436,16 @@ async function runClone(argv) {
   } else {
     printLines([
       `Cloned project ${target.projectId} into ${targetDir} (${fileCount} files).`,
-      "Next: cd in and run `craft status`."
+      nextStepHint(targetDir)
     ]);
   }
   return 0;
 }
 
+// src/commands/create.ts
+import { basename } from "node:path";
+import { createInterface } from "node:readline/promises";
+
 // src/commands/clone.ts
 import { existsSync as existsSync5 } from "node:fs";
 import { mkdir as mkdir4, readdir as readdir4, writeFile as writeFile4 } from "node:fs/promises";
@@ -42401,6 +42479,36 @@ async function defaultCloneDir2(base) {
   }
   throw new CliError(`Could not find a free directory name near ${base}; pass [dir] explicitly.`, 2);
 }
+async function assertUsableCloneTarget2({
+  targetDir,
+  zipFilePaths
+}) {
+  if (!existsSync5(targetDir)) {
+    return;
+  }
+  const existing = await readdir4(targetDir);
+  const visible = existing.filter((name) => !shouldSkipWorkspaceName(name));
+  const collisions = zipFilePaths.filter((relative2) => {
+    try {
+      return existsSync5(joinUnderWorkspaceRoot(targetDir, relative2));
+    } catch {
+      return false;
+    }
+  });
+  if (visible.length === 0 && collisions.length === 0) {
+    return;
+  }
+  throw new CliError([
+    `Refusing to clone into ${targetDir}:`,
+    ...visible.map((name) => `  ${name} — pre-existing and would be mixed into the new workspace`),
+    ...collisions.map((relative2) => `  ${relative2} — the project snapshot would overwrite it`),
+    "Entries the workspace scanner ignores (.git/, .gitignore, other dotfiles) may pre-exist; move the listed items or pick a different [dir]."
+  ].join(`
+`), 2);
+}
+function nextStepHint2(targetDir) {
+  return targetDir === process.cwd() ? "Next: run `craft status`." : "Next: cd in and run `craft status`.";
+}
 async function downloadAndUnpackSnapshot2({
   client,
   projectId,
@@ -42411,12 +42519,8 @@ async function downloadAndUnpackSnapshot2({
   const paths = Object.keys(entries);
   const rootDir = zipRootDir2(paths);
   const targetDir = dirArg ? resolve5(dirArg) : await defaultCloneDir2(resolve5(rootDir));
-  if (existsSync5(targetDir)) {
-    const existing = await readdir4(targetDir);
-    if (existing.length > 0) {
-      throw new CliError(`Refusing to clone into non-empty directory ${targetDir}`, 2);
-    }
-  }
+  const zipFilePaths = paths.filter((path) => !path.endsWith("/")).map((path) => path.slice(rootDir.length + 1)).filter((relative2) => relative2 !== "");
+  await assertUsableCloneTarget2({ targetDir, zipFilePaths });
   await mkdir4(targetDir, { recursive: true });
   let fileCount = 0;
   for (const [path, bytes] of Object.entries(entries)) {
@@ -42444,21 +42548,46 @@ async function downloadAndUnpackSnapshot2({
 }
 
 // src/commands/create.ts
+var DIRECTORY_NAME_SEPARATORS = /[-_\s]+/;
+var UUID_IN_TEXT2 = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+var DIGITS_ONLY = /^\d+$/;
+var MAX_SYSTEM_MATCHES_SHOWN = 8;
+var NAME_RESOLUTION_PAGE_SIZE = 48;
+var NAME_RESOLUTION_MAX_PAGES = 10;
+function projectNameFromDirectory(dirName) {
+  return dirName.split(DIRECTORY_NAME_SEPARATORS).filter((word) => word.length > 0).map((word) => (word[0]?.toUpperCase() ?? "") + word.slice(1)).join(" ");
+}
 async function runCreate(argv) {
   const args = parseCommandArgs({
     argv,
     flags: {
       description: { type: "string" },
+      system: { type: "string" },
+      blank: { type: "boolean" },
       empty: { type: "boolean" },
       remote: { type: "string" },
       json: { type: "boolean" }
     },
     maxPositionals: 2
   });
-  const [name, dirArg] = args.positionals;
+  const [nameArg, dirPositional] = args.positionals;
+  if (!nameArg) {
+    throw new CliError('Usage: craft create <name> [dir] [--system <id|name> | --blank] — quote names with spaces, e.g. craft create "My World" (or `craft create .` to create here, named after this directory)', 2);
+  }
+  if (nameArg === "." && dirPositional !== undefined) {
+    throw new CliError('`craft create .` takes no [dir] — "." already means "create in the current directory, named after it". To pick the name yourself: craft create "My Name" .', 2);
+  }
+  const systemArg = stringFlag(args, "system");
+  const wantsBlank = args.booleans.has("blank") || args.booleans.has("empty");
+  if (systemArg && wantsBlank) {
+    throw new CliError("--system cannot combine with --blank/--empty — a project either builds on a system or starts from scratch.", 2);
+  }
+  const namedAfterCwd = nameArg === ".";
+  const name = namedAfterCwd ? projectNameFromDirectory(basename(process.cwd())) : nameArg;
   if (!name) {
-    throw new CliError('Usage: craft create <name> [dir] — quote names with spaces, e.g. craft create "My World"', 2);
+    throw new CliError('Could not derive a project name from the current directory — pass one explicitly: craft create "My World" .', 2);
   }
+  const dirArg = namedAfterCwd ? "." : dirPositional;
   const resolved = resolveRemote({ flagRemote: stringFlag(args, "remote") });
   const remote = resolved.remote;
   const client = createCliClient({
@@ -42468,14 +42597,25 @@ async function runCreate(argv) {
       loginHint: silentDefaultHint(resolved)
     })
   });
-  const description = stringFlag(args, "description");
-  const created = await client.createProject({
-    request: {
-      name,
-      ...description ? { description } : {},
-      ...args.booleans.has("empty") ? { seedStarterContent: false } : {}
-    }
+  const base = await resolveCreateBase({
+    client,
+    systemArg,
+    wantsBlank,
+    name,
+    nameArg,
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY && !args.booleans.has("json"))
   });
+  const description = stringFlag(args, "description");
+  const request = { name };
+  if (description) {
+    request.description = description;
+  }
+  if (base.kind === "system") {
+    request.systemProjectId = base.systemProjectId;
+  } else {
+    request.seedStarterContent = false;
+  }
+  const created = await client.createProject({ request });
   const { targetDir, fileCount } = await downloadAndUnpackSnapshot2({
     client,
     projectId: created.projectId,
@@ -42485,19 +42625,184 @@ async function runCreate(argv) {
     printJson({
       projectId: created.projectId,
       containerId: created.containerId,
+      name,
       remote,
       dir: targetDir,
-      files: fileCount
+      files: fileCount,
+      system: base.kind === "system" ? { projectId: base.systemProjectId, name: base.systemName } : null
     });
   } else {
+    const fromSystem = base.kind === "system" ? ` from system ${base.systemName ? `"${base.systemName}" ` : ""}(${base.systemProjectId})` : "";
     printLines([
-      `Created project "${name}" (${created.projectId}) on ${remote} ` + `(${describeRemoteSource(resolved)}).`,
+      `Created project "${name}" (${created.projectId}) on ${remote} ` + `(${describeRemoteSource(resolved)})${fromSystem}.`,
+      ...namedAfterCwd ? [
+        'Named after the current directory — `craft create "My Name" .` picks the name yourself.'
+      ] : [],
       `Cloned into ${targetDir} (${fileCount} files).`,
-      "Next: cd in and run `craft status`."
+      nextStepHint2(targetDir)
     ]);
   }
   return 0;
 }
+async function resolveCreateBase({
+  client,
+  systemArg,
+  wantsBlank,
+  name,
+  nameArg,
+  interactive
+}) {
+  if (systemArg) {
+    return await resolveSystemArg({ client, value: systemArg });
+  }
+  if (wantsBlank) {
+    return { kind: "blank" };
+  }
+  const catalog = await client.fetchSystems();
+  const featured = catalog?.featured ?? [];
+  if (featured.length === 0) {
+    return { kind: "blank" };
+  }
+  if (!interactive) {
+    throw new CliError(pickBaseGuidance({ nameArg, featured }), 2);
+  }
+  return await promptForBase({ name, featured });
+}
+async function resolveSystemArg({
+  client,
+  value
+}) {
+  const id = extractProjectId(value);
+  if (id) {
+    return { kind: "system", systemProjectId: id, systemName: null };
+  }
+  const catalog = await client.fetchSystems({
+    q: value,
+    limit: NAME_RESOLUTION_PAGE_SIZE
+  });
+  if (!catalog) {
+    throw new CliError("This server does not support creating from a system yet — update the server, or omit --system.", 1);
+  }
+  const candidates = [...catalog.featured, ...catalog.community];
+  let cursor = catalog.communityNextCursor;
+  for (let page = 1;cursor && page < NAME_RESOLUTION_MAX_PAGES; page += 1) {
+    const next = await client.fetchSystems({
+      q: value,
+      cursor,
+      limit: NAME_RESOLUTION_PAGE_SIZE
+    });
+    if (!next) {
+      break;
+    }
+    candidates.push(...next.community);
+    cursor = next.communityNextCursor;
+  }
+  const exact = candidates.filter((system) => system.name.toLowerCase() === value.toLowerCase());
+  const pool = exact.length > 0 ? exact : candidates;
+  const [only] = pool;
+  if (only && pool.length === 1) {
+    return {
+      kind: "system",
+      systemProjectId: only.projectId,
+      systemName: only.name
+    };
+  }
+  if (pool.length === 0) {
+    throw new CliError(`No published system matches "${value}" — browse the catalog with \`craft systems\`, then pass a name or id.`, 2);
+  }
+  throw new CliError([
+    `"${value}" matches ${pool.length} published systems — pass the id instead:`,
+    ...pool.slice(0, MAX_SYSTEM_MATCHES_SHOWN).map((system) => `  ${systemChoiceLabel(system)}  ${system.projectId}`)
+  ].join(`
+`), 2);
+}
+function extractProjectId(value) {
+  const matches = value.match(UUID_IN_TEXT2);
+  return matches?.at(-1)?.toLowerCase() ?? null;
+}
+function systemChoiceLabel(system) {
+  const parts = [
+    system.name,
+    system.gameSystemName ? `— ${system.gameSystemName}` : null,
+    system.ownerUsername ? `by ${system.ownerUsername}` : null,
+    system.official ? "(official)" : null
+  ];
+  return parts.filter((part) => Boolean(part)).join(" ");
+}
+function pickBaseGuidance({
+  nameArg,
+  featured
+}) {
+  const quoted = nameArg !== "." && nameArg.includes(" ") ? `"${nameArg}"` : nameArg;
+  return [
+    "Pick a base for the new project — new projects usually build on a published system:",
+    `  craft create ${quoted} --system <id|name>   # build on a system`,
+    `  craft create ${quoted} --blank              # start from scratch (an empty project)`,
+    "",
+    "Featured systems:",
+    ...featured.map((system) => `  ${systemChoiceLabel(system)}  ${system.projectId}`),
+    "",
+    "Browse or search the full catalog with `craft systems`."
+  ].join(`
+`);
+}
+function parseBaseAnswer(answer, featured) {
+  const trimmed = answer.trim();
+  const lowered = trimmed.toLowerCase();
+  if (lowered === "q" || lowered === "quit") {
+    return "quit";
+  }
+  if (lowered === "b" || lowered === "blank") {
+    return { kind: "blank" };
+  }
+  if (DIGITS_ONLY.test(trimmed)) {
+    const chosen = featured[Number.parseInt(trimmed, 10) - 1];
+    return chosen ? {
+      kind: "system",
+      systemProjectId: chosen.projectId,
+      systemName: chosen.name
+    } : "invalid";
+  }
+  const id = extractProjectId(trimmed);
+  if (id) {
+    const known = featured.find((system) => system.projectId === id);
+    return {
+      kind: "system",
+      systemProjectId: id,
+      systemName: known?.name ?? null
+    };
+  }
+  return "invalid";
+}
+async function promptForBase({
+  name,
+  featured
+}) {
+  printLines([
+    `Choose a base for "${name}" — new projects usually build on a system:`,
+    ...featured.map((system, index) => `  ${index + 1}) ${systemChoiceLabel(system)}`),
+    "  b) Blank project (empty — author your own file types)",
+    "More systems: `craft systems`, then rerun with --system <id|name>."
+  ]);
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    for (;; ) {
+      const answer = await rl.question(`Pick 1-${featured.length}, b for blank, or q to cancel: `);
+      const choice = parseBaseAnswer(answer, featured);
+      if (choice === "quit") {
+        throw new CliError("Cancelled — nothing was created.", 2);
+      }
+      if (choice !== "invalid") {
+        return choice;
+      }
+      printLines([
+        `Enter a number between 1 and ${featured.length}, a system id, b, or q.`
+      ]);
+    }
+  } finally {
+    rl.close();
+  }
+}
 // ../../node_modules/.bun/uuid@11.1.0/node_modules/uuid/dist/esm/rng.js
 import { randomFillSync } from "crypto";
 var rnds8Pool = new Uint8Array(256);
@@ -43495,7 +43800,7 @@ async function workspacePin() {
 
 // src/commands/image.ts
 import { readFile as readFile6 } from "node:fs/promises";
-import { basename, isAbsolute as isAbsolute2 } from "node:path";
+import { basename as basename2, isAbsolute as isAbsolute2 } from "node:path";
 
 // ../shared/src/ledger-constants.ts
 var SYSTEM_ACCOUNTS = {
@@ -43753,7 +44058,7 @@ async function runImageUpload(argv) {
     })
   });
   const form = new FormData;
-  form.append("file", new File([new Uint8Array(bytes)], basename(filePath)));
+  form.append("file", new File([new Uint8Array(bytes)], basename2(filePath)));
   let result;
   try {
     result = await client.uploadImage({
@@ -43768,7 +44073,7 @@ async function runImageUpload(argv) {
     return 0;
   }
   printLines([
-    `Uploaded ${basename(filePath)} (${result.width}x${result.height}, ${Math.round(result.bytes / 1024)}KB as webp):`,
+    `Uploaded ${basename2(filePath)} (${result.width}x${result.height}, ${Math.round(result.bytes / 1024)}KB as webp):`,
     `  ${result.image.url ?? "<no url returned>"}`,
     "",
     `To use it, set this object as the file's "image" field and push:`,
@@ -43850,7 +44155,7 @@ async function runImageGenerate(argv) {
   const referenceImageUrls = [];
   for (const reference of localReferenceImages) {
     const form = new FormData;
-    form.append("file", new File([new Uint8Array(reference.bytes)], basename(reference.path)));
+    form.append("file", new File([new Uint8Array(reference.bytes)], basename2(reference.path)));
     let uploaded;
     try {
       uploaded = await client.uploadImage({
@@ -43953,7 +44258,7 @@ function toActionableError(error48, operation = "generation") {
 
 // src/commands/import.ts
 import { readFile as readFile7 } from "node:fs/promises";
-import { basename as basename2 } from "node:path";
+import { basename as basename3 } from "node:path";
 async function runImport(argv) {
   const args = parseCommandArgs({
     argv,
@@ -43986,7 +44291,7 @@ async function runImport(argv) {
     throw new CliError(`Could not read "${zipPath}": ${error48 instanceof Error ? error48.message : String(error48)}`, 2);
   }
   const form = new FormData;
-  form.append("file", new File([new Uint8Array(zipBytes)], basename2(zipPath)));
+  form.append("file", new File([new Uint8Array(zipBytes)], basename3(zipPath)));
   if (args.booleans.has("dry-run")) {
     form.append("dryRun", "true");
   }
@@ -49623,6 +49928,138 @@ function renderStatus(status, openConflicts = []) {
   return lines;
 }
 
+// src/commands/systems.ts
+var MAX_NAME_WIDTH = 40;
+var MAX_BLURB_LENGTH = 100;
+async function runSystems(argv) {
+  const args = parseCommandArgs({
+    argv,
+    flags: {
+      tag: { type: "string", repeatable: true },
+      community: { type: "boolean" },
+      cursor: { type: "string" },
+      limit: { type: "string" },
+      remote: { type: "string" },
+      json: { type: "boolean" }
+    },
+    maxPositionals: 1
+  });
+  const [query] = args.positionals;
+  const tags = args.strings.get("tag") ?? [];
+  const cursor = stringFlag(args, "cursor");
+  const limit = parseLimit(stringFlag(args, "limit"));
+  const pinned = await workspaceRemote2();
+  const resolved = resolveRemote({
+    flagRemote: stringFlag(args, "remote"),
+    context: pinned ? { remote: pinned, source: "workspace" } : null
+  });
+  const remote = resolved.remote;
+  const client = createCliClient({
+    remote,
+    auth: await resolveTokenProvider({
+      remote,
+      loginHint: silentDefaultHint(resolved)
+    })
+  });
+  const catalog = await client.fetchSystems({
+    ...query ? { q: query } : {},
+    ...tags.length > 0 ? { tags } : {},
+    ...cursor ? { cursor } : {},
+    ...limit !== undefined ? { limit } : {}
+  });
+  if (!catalog) {
+    throw new CliError("This server does not support browsing systems from the CLI yet — update the server, or browse systems in the Craft app.", 1);
+  }
+  if (args.booleans.has("json")) {
+    printJson({
+      remote,
+      featured: catalog.featured.map(withIsoPublishedAt),
+      community: catalog.community.map(withIsoPublishedAt),
+      communityNextCursor: catalog.communityNextCursor
+    });
+    return 0;
+  }
+  const isFiltered = Boolean(query) || tags.length > 0;
+  const showFeatured = !(args.booleans.has("community") || cursor);
+  const featured = showFeatured ? catalog.featured : [];
+  const lines = [];
+  if (featured.length > 0) {
+    lines.push(`${featured.length} featured system(s) on ${remote}:`, ...systemLines(featured), "");
+  }
+  if (catalog.community.length > 0) {
+    const label = isFiltered ? `matching community system(s) on ${remote}` : `community system(s) on ${remote}, newest first`;
+    lines.push(`${catalog.community.length} ${label}:`, ...systemLines(catalog.community));
+    if (catalog.communityNextCursor) {
+      lines.push(`  …more: craft systems --community --cursor ${catalog.communityNextCursor}`);
+    }
+    lines.push("");
+  }
+  if (featured.length === 0 && catalog.community.length === 0) {
+    printLines([
+      isFiltered ? `No published systems match${query ? ` "${query}"` : ""}${tags.length > 0 ? ` (tags: ${tags.join(", ")})` : ""} on ${remote}.` : `No published systems on ${remote} yet.`
+    ]);
+    return 0;
+  }
+  lines.push('Start a project from one: craft create "My World" --system <id|name>');
+  if (!isFiltered) {
+    lines.push("Search: craft systems <query> — narrow by tag with --tag <tag>.");
+  }
+  printLines(lines);
+  return 0;
+}
+function parseLimit(raw) {
+  if (raw === undefined) {
+    return;
+  }
+  const limit = Number.parseInt(raw, 10);
+  if (!Number.isFinite(limit) || limit < 1) {
+    throw new CliError(`--limit must be a positive number, got "${raw}"`, 2);
+  }
+  return limit;
+}
+function withIsoPublishedAt(system) {
+  return {
+    ...system,
+    publishedAt: system.publishedAt ? toIsoTimestamp(system.publishedAt) : null
+  };
+}
+function systemLines(systems) {
+  const nameWidth = Math.min(MAX_NAME_WIDTH, Math.max(...systems.map((system) => system.name.length)));
+  return systems.flatMap((system) => {
+    const name = system.name.length > MAX_NAME_WIDTH ? `${system.name.slice(0, MAX_NAME_WIDTH - 1)}…` : system.name.padEnd(nameWidth);
+    const details = [
+      system.gameSystemName,
+      system.ownerUsername ? `by ${system.ownerUsername}` : null,
+      system.official ? "official" : null,
+      `${system.fileCount ?? 0} files`,
+      `${system.cloneCount} clones`,
+      system.tags.length > 0 ? `tags: ${system.tags.join(", ")}` : null
+    ].filter((part) => Boolean(part)).join(" · ");
+    const lines = [`  ${name}  ${system.projectId}  ${details}`];
+    const blurb = descriptionBlurb(system.description);
+    if (blurb) {
+      lines.push(`      ${blurb}`);
+    }
+    return lines;
+  });
+}
+function descriptionBlurb(description) {
+  const firstLine = description?.trim().split(`
+`, 1)[0]?.trim();
+  if (!firstLine) {
+    return null;
+  }
+  return firstLine.length > MAX_BLURB_LENGTH ? `${firstLine.slice(0, MAX_BLURB_LENGTH - 1)}…` : firstLine;
+}
+async function workspaceRemote2() {
+  try {
+    const workspace = await loadWorkspaceContext();
+    return workspace.config.remote;
+  } catch {
+    return null;
+  }
+}
+
 // src/commands/type.ts
 import { existsSync as existsSync9 } from "node:fs";
 var TYPE_USAGE = "Usage: craft type new <Name> [--markdown] [--designation <token>] [--category <token>]";
@@ -49800,9 +50237,16 @@ var AUTH_COMMAND_LINES_DEV = `  login [--remote <env|origin>]  Sign in with your
                                  Show or set the environment used from this directory
 `;
 var HELP_COMMAND_LINES = `  clone <projectIdOrUrl> [dir]   Download a project as a local workspace
-  create <name> [dir] [--description "..."] [--empty]
-                                 Create a new project and clone it locally
-                                 (--empty skips the starter file types)
+                                 ([dir] may be "." for the current directory)
+  create <name> [dir] [--system <id|name> | --blank] [--description "..."]
+                                 Create a new project and clone it locally,
+                                 built on a published system (--system) or
+                                 empty (--blank). Run with neither to pick
+                                 from the featured systems.
+                                 craft create . \u2192 here, named after the dir
+  systems [query] [--tag <t>] [--community] [--limit <n>]
+                                 Browse published game systems to build on
+                                 (curated featured row + community catalog)
   projects                       List the projects your account owns
   log <path> [--limit <n>]       Show a file's version history (newest first)
   status [--remote] [--full]     Show local changes (and remote drift with --remote;
@@ -49882,22 +50326,61 @@ Sign out \u2014 forget the credentials stored on this machine.
   clone: `Usage: craft clone <projectIdOrUrl> [dir]
 
 Download a project as a local workspace. Accepts a project id or a pasted
-project URL. [dir] defaults to a folder named after the project.
+project URL. [dir] defaults to a new folder named after the project; pass
+"." (or any path) to choose the destination. The target may already hold
+entries the workspace ignores (.git/, .gitignore, other dotfiles), but
+nothing the snapshot would mix with or overwrite.
+
+Examples:
+  craft clone <id>              # into ./<project-name>/
+  craft clone <id> my-dir       # into ./my-dir/
+  craft clone <id> .            # into the current directory
 `,
-  create: `Usage: craft create <name> [dir] [--description "..."] [--empty]
+  create: `Usage: craft create <name> [dir] [--system <id|name> | --blank] [--description "..."]
+       craft create .           (create here, named after the current directory)
 
 Create a new project on the server and clone it into [dir] (defaults to a
-folder named after the project).
-
-By default the project seeds the standard starter file types (Character,
-Location, Equipment, Game Start, GM Instructions) plus example files \u2014
-generic fantasy-flavored; you may retool them. --empty skips all of that so
-you author every file type yourself (see \`craft type new\`).
+new folder named after the project; "." uses the current directory \u2014
+pre-existing dotfiles like .git/ are fine).
+
+New projects usually build on a published game system \u2014 a project shipping
+file types, rules content, and GM instructions to start from:
+
+  --system <id|name>  clone that system as your starting point
+                      (browse them with \`craft systems\`)
+  --blank             start with an empty project \u2014 no file types, no
+                      content; author your own with \`craft type new\` and
+                      push them with --include-types (--empty is an older
+                      alias)
+
+With neither, an interactive run offers the featured systems as a picker;
+scripts and agents must pass --system or --blank explicitly.
+
+Examples:
+  craft create "My World" --system "Ashes RPG"  # build on a system
+  craft create "My World" --blank               # creates ./my-world/
+  craft create "My World" my-dir --blank        # creates ./my-dir/
+  craft create "My World" . --blank             # into the current directory
+  craft create . --blank                        # here, named after the dir
 `,
   projects: `Usage: craft projects
 
 List every project your account owns (name, id, last update, file count) \u2014
 newest activity first. Clone one with \`craft clone <projectId>\`.
+`,
+  systems: `Usage: craft systems [query] [--tag <tag>]... [--community] [--limit <n>] [--json]
+
+Browse published game systems \u2014 projects that ship file types, rules
+content, and GM instructions for other projects to build on. The featured
+row is curated; everything else is the community catalog, newest publish
+first.
+
+[query] matches name, system label, description, and author. --tag keeps
+only systems carrying every given tag (repeatable). --community lists the
+community catalog alone. Long listings page with --cursor <cursor>, printed
+at the end of each page (--json carries it as communityNextCursor).
+
+Start a project from a system: craft create "My World" --system <id|name>.
 `,
   log: `Usage: craft log <path> [--limit <n>]
 
@@ -50155,18 +50638,35 @@ A cloned workspace always syncs with the server it was cloned from.
 
 Download a project as a local workspace. A full project URL carries its
 origin; a bare project id uses the current environment (see \`craft help
-env\`). [dir] defaults to a folder named after the project.
+env\`). [dir] defaults to a new folder named after the project; pass "."
+(or any path) to choose the destination. The target may already hold
+entries the workspace ignores (.git/, .gitignore, other dotfiles), but
+nothing the snapshot would mix with or overwrite.
+
+Examples:
+  craft clone <id>              # into ./<project-name>/
+  craft clone <id> my-dir       # into ./my-dir/
+  craft clone <id> .            # into the current directory
 `,
-  create: `Usage: craft create <name> [dir] [--description "..."] [--empty]
+  create: `Usage: craft create <name> [dir] [--system <id|name> | --blank] [--description "..."]
+       craft create .           (create here, named after the current directory)
 
 Create a new project on the server and clone it into [dir] (defaults to a
-folder named after the project). Targets the current environment \u2014 check
-with \`craft env\`.
-
-By default the project seeds the standard starter file types (Character,
-Location, Equipment, Game Start, GM Instructions) plus example files \u2014
-generic fantasy-flavored; you may retool them. --empty skips all of that so
-you author every file type yourself (see \`craft type new\`).
+new folder named after the project; "." uses the current directory \u2014
+pre-existing dotfiles like .git/ are fine). Targets the current
+environment \u2014 check with \`craft env\`.
+
+New projects usually build on a published game system: --system <id|name>
+clones one as the starting point (browse with \`craft systems\`), --blank
+starts with an empty project (no file types; --empty is an older alias).
+With neither, an interactive run offers the featured systems as a picker;
+scripts and agents must pass --system or --blank explicitly.
+
+Examples:
+  craft create "My World" --system "Ashes RPG"  # build on a system
+  craft create "My World" --blank               # creates ./my-world/
+  craft create "My World" my-dir --blank        # creates ./my-dir/
+  craft create . --blank                        # here, named after the dir
 `,
   projects: `Usage: craft projects
 
@@ -50174,6 +50674,21 @@ List every project your account owns (name, id, last update, file count) \u2014
 newest activity first. Uses the current workspace's remote when run inside
 one; otherwise the current environment (see \`craft help env\`). Clone one
 with \`craft clone <projectId>\`.
+`,
+  systems: `Usage: craft systems [query] [--tag <tag>]... [--community] [--limit <n>] [--json]
+
+Browse published game systems \u2014 projects that ship file types, rules
+content, and GM instructions for other projects to build on. The featured
+row is curated; everything else is the community catalog, newest publish
+first. Uses the current workspace's remote when run inside one; otherwise
+the current environment (see \`craft help env\`).
+
+[query] matches name, system label, description, and author. --tag keeps
+only systems carrying every given tag (repeatable). --community lists the
+community catalog alone. Long listings page with --cursor <cursor>, printed
+at the end of each page (--json carries it as communityNextCursor).
+
+Start a project from a system: craft create "My World" --system <id|name>.
 `
 };
 function commandHelp(topic) {
@@ -50189,6 +50704,7 @@ var COMMANDS = {
   clone: runClone,
   create: runCreate,
   projects: runProjects,
+  systems: runSystems,
   log: runLog,
   status: runStatus,
   check: runCheck,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@craftrpgs/cli",
-  "version": "0.1.2",
-  "description": "Sync Craft projects with a local folder \u2014 clone, edit with any coding agent, push back.",
+  "version": "0.1.4",
+  "description": "Sync Craft projects with a local folder — clone, edit with any coding agent, push back.",
   "license": "UNLICENSED",
   "homepage": "https://craftrpgs.com",
   "type": "module",