gistajs 0.0.6 → 0.0.8

package/dist/bin.cjs

@@ -64,7 +64,7 @@ var import_node_process2 = __toESM(require("process"), 1);
 var tar = __toESM(require("tar"), 1);
 
 // src/git.ts
-var import_node_child_process = require("child_process");
+var import_node_child_process2 = require("child_process");
 
 // src/prompt.ts
 var import_node_process = __toESM(require("process"), 1);
@@ -116,6 +116,24 @@ async function confirm(rl, message) {
   return answer === "y" || answer === "yes";
 }
 
+// src/subprocess.ts
+var import_node_child_process = require("child_process");
+async function run(command, args, cwd) {
+  await new Promise((resolve2, reject) => {
+    let child = (0, import_node_child_process.spawn)(command, args, {
+      cwd,
+      stdio: "inherit"
+    });
+    child.once("error", reject);
+    child.once("exit", (code) => {
+      if (code === 0) resolve2();
+      else {
+        reject(new Error(`${command} ${args.join(" ")} exited with code ${code}`));
+      }
+    });
+  });
+}
+
 // src/git.ts
 var defaultDeps = {
   promptForGitIdentity,
@@ -164,7 +182,7 @@ async function resolveGitIdentity(cwd, deps) {
 }
 function readGitConfig(cwd, key) {
   try {
-    return (0, import_node_child_process.execFileSync)("git", ["config", "--get", key], {
+    return (0, import_node_child_process2.execFileSync)("git", ["config", "--get", key], {
       cwd,
       encoding: "utf-8"
     }).trim();
@@ -172,22 +190,6 @@ function readGitConfig(cwd, key) {
     return "";
   }
 }
-async function run(command, args, cwd) {
-  await new Promise((resolve2, reject) => {
-    let child = (0, import_node_child_process.spawn)(command, args, {
-      cwd,
-      stdio: "inherit"
-    });
-    child.once("error", reject);
-    child.once("exit", (code) => {
-      if (code === 0) resolve2();
-      else
-        reject(
-          new Error(`${command} ${args.join(" ")} exited with code ${code}`)
-        );
-    });
-  });
-}
 
 // src/create.ts
 async function createProject(starter, options) {
@@ -314,28 +316,160 @@ async function assertSafeProjectRoot(root) {
   await (0, import_promises2.mkdir)(parent, { recursive: true });
 }
 
+// src/diff.ts
+var import_node_child_process3 = require("child_process");
+var import_promises3 = require("fs/promises");
+var import_node_os2 = require("os");
+var import_node_path2 = require("path");
+var defaultDeps2 = {
+  mkdtemp: import_promises3.mkdtemp,
+  rm: import_promises3.rm,
+  run,
+  runOutput
+};
+async function diffStarter(starter, options, deps = defaultDeps2) {
+  if (!options.fromReleaseKey || !options.toReleaseKey) {
+    throw new Error("Diff requires both from and to release keys");
+  }
+  let root = await deps.mkdtemp((0, import_node_path2.join)((0, import_node_os2.tmpdir)(), "gistajs-diff-"));
+  let repoUrl = getStarterRepoUrl(starter);
+  let fromTag = resolveStarterTagName(starter.slug, options.fromReleaseKey);
+  let toTag = resolveStarterTagName(starter.slug, options.toReleaseKey);
+  try {
+    await git2(root, ["init", "-q"], deps);
+    await git2(root, ["remote", "add", "origin", repoUrl], deps);
+    await fetchTag(root, fromTag, repoUrl, deps);
+    await fetchTag(root, toTag, repoUrl, deps);
+    return await gitOutput(
+      root,
+      ["diff", "--stat", `refs/tags/${fromTag}`, `refs/tags/${toTag}`],
+      repoUrl,
+      deps
+    );
+  } finally {
+    await deps.rm(root, { recursive: true, force: true });
+  }
+}
+function resolveStarterTagName(starter, releaseKey) {
+  return `${starter}/${releaseKey}`;
+}
+function getStarterRepoUrl(starter) {
+  return `https://github.com/${starter.repo}.git`;
+}
+async function fetchTag(cwd, tag, repoUrl, deps) {
+  try {
+    await git2(
+      cwd,
+      ["fetch", "--quiet", "--no-tags", "origin", `refs/tags/${tag}:refs/tags/${tag}`],
+      deps
+    );
+  } catch (error) {
+    throw new Error(
+      `Failed to fetch tag ${tag} from ${repoUrl}: ${getErrorMessage(error)}`
+    );
+  }
+}
+async function git2(cwd, args, deps) {
+  await deps.run("git", args, cwd);
+}
+async function gitOutput(cwd, args, repoUrl, deps) {
+  try {
+    return await deps.runOutput("git", args, cwd);
+  } catch (error) {
+    throw new Error(
+      `Failed to diff starter snapshots from ${repoUrl}: ${getErrorMessage(error)}`
+    );
+  }
+}
+function getErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function runOutput(command, args, cwd) {
+  return await new Promise((resolve2, reject) => {
+    let stdout = "";
+    let stderr = "";
+    let child = (0, import_node_child_process3.spawn)(command, args, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.once("error", reject);
+    child.once("exit", (code) => {
+      if (code === 0) {
+        resolve2(stdout);
+        return;
+      }
+      let detail = stderr.trim();
+      reject(
+        new Error(
+          detail || `${command} ${args.join(" ")} exited with code ${code}`
+        )
+      );
+    });
+  });
+}
+
 // src/cli.ts
-async function runCli(argv = import_node_process3.default.argv.slice(2)) {
+var defaultDeps3 = {
+  loadCatalog,
+  createProject,
+  diffStarter,
+  promptForStarter,
+  stdout: console
+};
+var UsageError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+  }
+};
+async function runCli(argv = import_node_process3.default.argv.slice(2), deps = defaultDeps3) {
   let [command, ...rest] = argv;
   if (!command || command === "--help" || command === "-h") {
-    printHelp();
+    deps.stdout.log(getHelpText());
     return;
   }
-  if (command !== "create") {
-    throw new Error(`Unknown command: ${command}`);
-  }
-  let options = parseCreateArgs(rest);
-  let catalog = await loadCatalog(options.catalogUrl);
-  let starterName = options.starter || await promptForStarter(catalog);
-  let starter = catalog.find((entry) => entry.slug === starterName);
-  if (!starter) {
-    throw new Error(`Unknown starter: ${starterName}`);
+  if (command === "create") {
+    let options = parseCreateArgs(rest);
+    if (!options.projectName) {
+      throw new UsageError("Project name is required");
+    }
+    let catalog = await deps.loadCatalog(options.catalogUrl);
+    let starterName = options.starter || await deps.promptForStarter(catalog);
+    let starter = catalog.find((entry) => entry.slug === starterName);
+    if (!starter) {
+      throw new UsageError(`Unknown starter: ${starterName}`);
+    }
+    let root = await deps.createProject(starter, options);
+    deps.stdout.log(`Created ${starter.slug} project in ${root}`);
+    return;
   }
-  if (!options.projectName) {
-    throw new Error("Project name is required");
+  if (command === "diff") {
+    let options = parseDiffArgs(rest);
+    if (!options.starter) {
+      throw new UsageError("Starter is required");
+    }
+    if (!options.fromReleaseKey) {
+      throw new UsageError("From release key is required");
+    }
+    if (!options.toReleaseKey) {
+      throw new UsageError("To release key is required");
+    }
+    let catalog = await deps.loadCatalog(options.catalogUrl);
+    let starter = catalog.find((entry) => entry.slug === options.starter);
+    if (!starter) {
+      throw new UsageError(`Unknown starter: ${options.starter}`);
+    }
+    let output = await deps.diffStarter(starter, options);
+    deps.stdout.log(output.trimEnd());
+    return;
   }
-  let root = await createProject(starter, options);
-  console.log(`Created ${starter.slug} project in ${root}`);
+  throw new UsageError(`Unknown command: ${command}`);
 }
 async function main() {
   try {
@@ -343,6 +477,9 @@ async function main() {
   } catch (error) {
     let message = error instanceof Error ? error.message : String(error);
     console.error(message);
+    if (error instanceof UsageError) {
+      console.error(getHelpText());
+    }
     import_node_process3.default.exitCode = 1;
   }
 }
@@ -359,7 +496,7 @@ function parseCreateArgs(argv) {
       continue;
     }
     if (arg === "--starter") {
-      if (!argv[index + 1]) throw new Error("--starter requires a value");
+      if (!argv[index + 1]) throw new UsageError("--starter requires a value");
       options.starter = argv[index + 1];
       index += 1;
       continue;
@@ -373,22 +510,59 @@ function parseCreateArgs(argv) {
       continue;
     }
     if (arg === "--catalog-url") {
-      if (!argv[index + 1]) throw new Error("--catalog-url requires a value");
+      if (!argv[index + 1]) {
+        throw new UsageError("--catalog-url requires a value");
+      }
       options.catalogUrl = argv[index + 1];
       index += 1;
       continue;
     }
-    throw new Error(`Unknown argument: ${arg}`);
+    throw new UsageError(`Unknown argument: ${arg}`);
   }
   return options;
 }
-function printHelp() {
-  console.log(
-    [
-      "Usage:",
-      "  gistajs create <project-name> [--starter <slug>] [--no-install] [--no-git]"
-    ].join("\n")
-  );
+function parseDiffArgs(argv) {
+  let options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    let arg = argv[index];
+    if (!arg) continue;
+    if (!arg.startsWith("--") && !options.starter) {
+      options.starter = arg;
+      continue;
+    }
+    if (!arg.startsWith("--") && !options.fromReleaseKey) {
+      options.fromReleaseKey = arg;
+      continue;
+    }
+    if (!arg.startsWith("--") && !options.toReleaseKey) {
+      options.toReleaseKey = arg;
+      continue;
+    }
+    if (arg === "--catalog-url") {
+      if (!argv[index + 1]) {
+        throw new UsageError("--catalog-url requires a value");
+      }
+      options.catalogUrl = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    throw new UsageError(`Unknown argument: ${arg}`);
+  }
+  return options;
+}
+function getHelpText() {
+  return [
+    "Usage:",
+    "  gistajs create <project-name> [--starter <slug>] [--no-install] [--no-git]",
+    "  gistajs diff <starter> <from-release-key> <to-release-key>",
+    "",
+    "Examples:",
+    "  gistajs create my-app",
+    "  gistajs create my-app --starter website",
+    "  gistajs diff auth 2026-03-28-001 2026-03-29-001",
+    "",
+    "Run `gistajs` with no arguments to show this help."
+  ].join("\n");
 }
 
 // src/bin.ts

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+
 type StarterSpec = {
     slug: string;
     repo: string;
@@ -12,9 +14,37 @@ type CreateOptions = {
     git?: boolean;
     catalogUrl?: string;
 };
+type DiffOptions = {
+    starter?: string;
+    fromReleaseKey?: string;
+    toReleaseKey?: string;
+    catalogUrl?: string;
+};
 
-declare function runCli(argv?: string[]): Promise<void>;
+declare function loadCatalog(url?: string): Promise<StarterSpec[]>;
 
 declare function createProject(starter: StarterSpec, options: CreateOptions): Promise<string>;
 
-export { type CreateOptions, type StarterSpec, createProject, runCli };
+declare function run(command: string, args: string[], cwd: string): Promise<void>;
+
+type DiffDeps = {
+    mkdtemp: typeof mkdtemp;
+    rm: typeof rm;
+    run: typeof run;
+    runOutput: typeof runOutput;
+};
+declare function diffStarter(starter: StarterSpec, options: DiffOptions, deps?: DiffDeps): Promise<string>;
+declare function runOutput(command: string, args: string[], cwd: string): Promise<string>;
+
+declare function promptForStarter(starters: StarterSpec[]): Promise<string>;
+
+type CliDeps = {
+    loadCatalog: typeof loadCatalog;
+    createProject: typeof createProject;
+    diffStarter: typeof diffStarter;
+    promptForStarter: typeof promptForStarter;
+    stdout: Pick<typeof console, 'log'>;
+};
+declare function runCli(argv?: string[], deps?: CliDeps): Promise<void>;
+
+export { type CreateOptions, type DiffOptions, type StarterSpec, createProject, diffStarter, runCli };

package/dist/index.js

@@ -49,7 +49,7 @@ import process2 from "process";
 import * as tar from "tar";
 
 // src/git.ts
-import { execFileSync, spawn } from "child_process";
+import { execFileSync } from "child_process";
 
 // src/prompt.ts
 import process from "process";
@@ -101,6 +101,24 @@ async function confirm(rl, message) {
   return answer === "y" || answer === "yes";
 }
 
+// src/subprocess.ts
+import { spawn } from "child_process";
+async function run(command, args, cwd) {
+  await new Promise((resolve2, reject) => {
+    let child = spawn(command, args, {
+      cwd,
+      stdio: "inherit"
+    });
+    child.once("error", reject);
+    child.once("exit", (code) => {
+      if (code === 0) resolve2();
+      else {
+        reject(new Error(`${command} ${args.join(" ")} exited with code ${code}`));
+      }
+    });
+  });
+}
+
 // src/git.ts
 var defaultDeps = {
   promptForGitIdentity,
@@ -157,22 +175,6 @@ function readGitConfig(cwd, key) {
     return "";
   }
 }
-async function run(command, args, cwd) {
-  await new Promise((resolve2, reject) => {
-    let child = spawn(command, args, {
-      cwd,
-      stdio: "inherit"
-    });
-    child.once("error", reject);
-    child.once("exit", (code) => {
-      if (code === 0) resolve2();
-      else
-        reject(
-          new Error(`${command} ${args.join(" ")} exited with code ${code}`)
-        );
-    });
-  });
-}
 
 // src/create.ts
 async function createProject(starter, options) {
@@ -299,28 +301,160 @@ async function assertSafeProjectRoot(root) {
   await mkdir(parent, { recursive: true });
 }
 
+// src/diff.ts
+import { spawn as spawn2 } from "child_process";
+import { mkdtemp as mkdtemp2, rm as rm2 } from "fs/promises";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join2 } from "path";
+var defaultDeps2 = {
+  mkdtemp: mkdtemp2,
+  rm: rm2,
+  run,
+  runOutput
+};
+async function diffStarter(starter, options, deps = defaultDeps2) {
+  if (!options.fromReleaseKey || !options.toReleaseKey) {
+    throw new Error("Diff requires both from and to release keys");
+  }
+  let root = await deps.mkdtemp(join2(tmpdir2(), "gistajs-diff-"));
+  let repoUrl = getStarterRepoUrl(starter);
+  let fromTag = resolveStarterTagName(starter.slug, options.fromReleaseKey);
+  let toTag = resolveStarterTagName(starter.slug, options.toReleaseKey);
+  try {
+    await git2(root, ["init", "-q"], deps);
+    await git2(root, ["remote", "add", "origin", repoUrl], deps);
+    await fetchTag(root, fromTag, repoUrl, deps);
+    await fetchTag(root, toTag, repoUrl, deps);
+    return await gitOutput(
+      root,
+      ["diff", "--stat", `refs/tags/${fromTag}`, `refs/tags/${toTag}`],
+      repoUrl,
+      deps
+    );
+  } finally {
+    await deps.rm(root, { recursive: true, force: true });
+  }
+}
+function resolveStarterTagName(starter, releaseKey) {
+  return `${starter}/${releaseKey}`;
+}
+function getStarterRepoUrl(starter) {
+  return `https://github.com/${starter.repo}.git`;
+}
+async function fetchTag(cwd, tag, repoUrl, deps) {
+  try {
+    await git2(
+      cwd,
+      ["fetch", "--quiet", "--no-tags", "origin", `refs/tags/${tag}:refs/tags/${tag}`],
+      deps
+    );
+  } catch (error) {
+    throw new Error(
+      `Failed to fetch tag ${tag} from ${repoUrl}: ${getErrorMessage(error)}`
+    );
+  }
+}
+async function git2(cwd, args, deps) {
+  await deps.run("git", args, cwd);
+}
+async function gitOutput(cwd, args, repoUrl, deps) {
+  try {
+    return await deps.runOutput("git", args, cwd);
+  } catch (error) {
+    throw new Error(
+      `Failed to diff starter snapshots from ${repoUrl}: ${getErrorMessage(error)}`
+    );
+  }
+}
+function getErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function runOutput(command, args, cwd) {
+  return await new Promise((resolve2, reject) => {
+    let stdout = "";
+    let stderr = "";
+    let child = spawn2(command, args, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.once("error", reject);
+    child.once("exit", (code) => {
+      if (code === 0) {
+        resolve2(stdout);
+        return;
+      }
+      let detail = stderr.trim();
+      reject(
+        new Error(
+          detail || `${command} ${args.join(" ")} exited with code ${code}`
+        )
+      );
+    });
+  });
+}
+
 // src/cli.ts
-async function runCli(argv = process3.argv.slice(2)) {
+var defaultDeps3 = {
+  loadCatalog,
+  createProject,
+  diffStarter,
+  promptForStarter,
+  stdout: console
+};
+var UsageError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+  }
+};
+async function runCli(argv = process3.argv.slice(2), deps = defaultDeps3) {
   let [command, ...rest] = argv;
   if (!command || command === "--help" || command === "-h") {
-    printHelp();
+    deps.stdout.log(getHelpText());
     return;
   }
-  if (command !== "create") {
-    throw new Error(`Unknown command: ${command}`);
-  }
-  let options = parseCreateArgs(rest);
-  let catalog = await loadCatalog(options.catalogUrl);
-  let starterName = options.starter || await promptForStarter(catalog);
-  let starter = catalog.find((entry) => entry.slug === starterName);
-  if (!starter) {
-    throw new Error(`Unknown starter: ${starterName}`);
+  if (command === "create") {
+    let options = parseCreateArgs(rest);
+    if (!options.projectName) {
+      throw new UsageError("Project name is required");
+    }
+    let catalog = await deps.loadCatalog(options.catalogUrl);
+    let starterName = options.starter || await deps.promptForStarter(catalog);
+    let starter = catalog.find((entry) => entry.slug === starterName);
+    if (!starter) {
+      throw new UsageError(`Unknown starter: ${starterName}`);
+    }
+    let root = await deps.createProject(starter, options);
+    deps.stdout.log(`Created ${starter.slug} project in ${root}`);
+    return;
   }
-  if (!options.projectName) {
-    throw new Error("Project name is required");
+  if (command === "diff") {
+    let options = parseDiffArgs(rest);
+    if (!options.starter) {
+      throw new UsageError("Starter is required");
+    }
+    if (!options.fromReleaseKey) {
+      throw new UsageError("From release key is required");
+    }
+    if (!options.toReleaseKey) {
+      throw new UsageError("To release key is required");
+    }
+    let catalog = await deps.loadCatalog(options.catalogUrl);
+    let starter = catalog.find((entry) => entry.slug === options.starter);
+    if (!starter) {
+      throw new UsageError(`Unknown starter: ${options.starter}`);
+    }
+    let output = await deps.diffStarter(starter, options);
+    deps.stdout.log(output.trimEnd());
+    return;
   }
-  let root = await createProject(starter, options);
-  console.log(`Created ${starter.slug} project in ${root}`);
+  throw new UsageError(`Unknown command: ${command}`);
 }
 function parseCreateArgs(argv) {
   let options = {
@@ -335,7 +469,7 @@ function parseCreateArgs(argv) {
       continue;
     }
     if (arg === "--starter") {
-      if (!argv[index + 1]) throw new Error("--starter requires a value");
+      if (!argv[index + 1]) throw new UsageError("--starter requires a value");
       options.starter = argv[index + 1];
       index += 1;
       continue;
@@ -349,24 +483,62 @@ function parseCreateArgs(argv) {
       continue;
     }
     if (arg === "--catalog-url") {
-      if (!argv[index + 1]) throw new Error("--catalog-url requires a value");
+      if (!argv[index + 1]) {
+        throw new UsageError("--catalog-url requires a value");
+      }
       options.catalogUrl = argv[index + 1];
       index += 1;
       continue;
     }
-    throw new Error(`Unknown argument: ${arg}`);
+    throw new UsageError(`Unknown argument: ${arg}`);
   }
   return options;
 }
-function printHelp() {
-  console.log(
-    [
-      "Usage:",
-      "  gistajs create <project-name> [--starter <slug>] [--no-install] [--no-git]"
-    ].join("\n")
-  );
+function parseDiffArgs(argv) {
+  let options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    let arg = argv[index];
+    if (!arg) continue;
+    if (!arg.startsWith("--") && !options.starter) {
+      options.starter = arg;
+      continue;
+    }
+    if (!arg.startsWith("--") && !options.fromReleaseKey) {
+      options.fromReleaseKey = arg;
+      continue;
+    }
+    if (!arg.startsWith("--") && !options.toReleaseKey) {
+      options.toReleaseKey = arg;
+      continue;
+    }
+    if (arg === "--catalog-url") {
+      if (!argv[index + 1]) {
+        throw new UsageError("--catalog-url requires a value");
+      }
+      options.catalogUrl = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    throw new UsageError(`Unknown argument: ${arg}`);
+  }
+  return options;
+}
+function getHelpText() {
+  return [
+    "Usage:",
+    "  gistajs create <project-name> [--starter <slug>] [--no-install] [--no-git]",
+    "  gistajs diff <starter> <from-release-key> <to-release-key>",
+    "",
+    "Examples:",
+    "  gistajs create my-app",
+    "  gistajs create my-app --starter website",
+    "  gistajs diff auth 2026-03-28-001 2026-03-29-001",
+    "",
+    "Run `gistajs` with no arguments to show this help."
+  ].join("\n");
 }
 export {
   createProject,
+  diffStarter,
   runCli
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gistajs",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Create Gista.js starter projects",
   "keywords": [
     "cli",
@@ -48,8 +48,10 @@
   },
   "scripts": {
     "build": "tsup",
-    "test": "vitest",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "typecheck": "tsc -b",
-    "np": "np"
+    "release:prepare": "pnpm typecheck && pnpm build && pnpm test",
+    "np": "pnpm release:prepare && np"
   }
 }