@usegraft/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Joseph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/add-UBAZMSP7.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import {
+  findConfig
+} from "./chunk-BUPFXTUG.js";
+
+// src/commands/add.ts
+import { dirname } from "path";
+import { GraftError } from "@usegraft/contracts";
+import { applyPlan, listItemNames, planAdd } from "@usegraft/registry";
+async function addCommand(options) {
+  if (options.names.length === 0) {
+    throw new GraftError({
+      code: "REGISTRY_ITEM_NOT_FOUND",
+      message: "graft add needs an item name.",
+      fix: `Usage: graft add <item>. Available items: ${listItemNames().join(", ") || "(none bundled)"}.`
+    });
+  }
+  const projectDir = dirname(findConfig(options.cwd));
+  const plan = planAdd(options.names, { targetDir: projectDir });
+  console.log(
+    `${options.dryRun ? "Would add" : "Adding"} ${plan.items.map((i) => `${i.name} (${i.type})`).join(", ")}:`
+  );
+  for (const file of plan.files) {
+    const state = file.identical ? "unchanged" : file.exists ? "overwrite" : "create";
+    console.log(`  ${state.padEnd(9)} ${file.relPath}`);
+  }
+  console.log(`  regenerate ${plan.barrel.relPath}`);
+  if (plan.mdxMap) console.log(`  regenerate ${plan.mdxMap.relPath}`);
+  if (options.dryRun) {
+    if (plan.conflicts.length > 0) {
+      console.log(
+        `
+${plan.conflicts.length} existing file(s) differ \u2014 re-run without --dry-run and with --overwrite to replace: ${plan.conflicts.join(", ")}`
+      );
+    }
+    printFollowups(plan);
+    return;
+  }
+  const result = applyPlan(plan, { overwrite: options.overwrite });
+  const parts = [`${result.written.length} written`];
+  if (result.skipped.length > 0) parts.push(`${result.skipped.length} unchanged`);
+  const regen = [plan.barrel.relPath, result.mdxMapPath].filter(Boolean).join(" + ");
+  console.log(
+    `
+Added ${plan.items.map((i) => i.name).join(", ")} (${parts.join(", ")}); ${regen} regenerated.`
+  );
+  printFollowups(plan);
+  console.log(
+    "It's live on your next `graft compile` \u2014 no graft.config.ts edit needed (the graft/ barrel wires modules; the MDX map wires blocks)."
+  );
+}
+function printFollowups(plan) {
+  const deps = Object.entries(plan.npmDependencies);
+  if (deps.length > 0) {
+    console.log("\nEnsure these packages are installed:");
+    for (const [pkg, spec] of deps) console.log(`  ${pkg}@${spec}`);
+  }
+}
+export {
+  addCommand
+};

package/dist/approvals-Z3EOK5AM.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import {
+  loadProjectEnv,
+  requireDatabaseUrl
+} from "./chunk-BUPFXTUG.js";
+
+// src/commands/approvals.ts
+import { userInfo } from "os";
+function operatorName() {
+  try {
+    return userInfo().username;
+  } catch {
+    return process.env.USERNAME ?? process.env.USER ?? "operator";
+  }
+}
+async function approvalsListCommand(options) {
+  loadProjectEnv(options.cwd);
+  const url = requireDatabaseUrl();
+  const { createDb, listPendingApprovals } = await import("@usegraft/db");
+  const handle = createDb(url);
+  try {
+    return await listPendingApprovals(handle.db);
+  } finally {
+    await handle.close();
+  }
+}
+async function decideCommand(options) {
+  loadProjectEnv(options.cwd);
+  const url = requireDatabaseUrl();
+  const [{ createDb, decideApproval }, { GraftError }] = await Promise.all([
+    import("@usegraft/db"),
+    import("@usegraft/contracts")
+  ]);
+  const handle = createDb(url);
+  try {
+    const row = await decideApproval(
+      handle.db,
+      options.id,
+      options.decision,
+      options.decidedBy ?? operatorName()
+    );
+    if (!row) {
+      throw new GraftError({
+        code: "APPROVAL_INVALID",
+        message: `No PENDING approval "${options.id}" exists \u2014 it may already be decided, consumed, or mistyped.`,
+        fix: "Run `graft approvals` to see what is actually pending; only pending approvals can be approved or denied.",
+        details: { id: options.id }
+      });
+    }
+    return row;
+  } finally {
+    await handle.close();
+  }
+}
+function formatApproval(row) {
+  const requester = row.requestedById ? `${row.requestedByKind}:${row.requestedById}` : row.requestedByKind;
+  return [
+    `${row.id}`,
+    `  function:  ${row.functionName}  (branch ${row.branchId})`,
+    `  requested: ${row.createdAt.toISOString()} by ${requester}`,
+    `  input:     ${JSON.stringify(row.input)}`
+  ].join("\n");
+}
+export {
+  approvalsListCommand,
+  decideCommand,
+  formatApproval
+};

package/dist/asset-FPEL463J.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import {
+  loadProjectEnv
+} from "./chunk-BUPFXTUG.js";
+
+// src/commands/asset.ts
+import { readFileSync, statSync } from "fs";
+import {
+  contentTypeFor,
+  createStorage,
+  defaultKeyFor,
+  storageConfigFromEnv
+} from "@usegraft/assets";
+import { GraftError } from "@usegraft/contracts";
+async function assetPutCommand(options) {
+  loadProjectEnv(options.cwd);
+  let body;
+  try {
+    statSync(options.file);
+    body = readFileSync(options.file);
+  } catch {
+    throw new GraftError({
+      code: "DOCUMENT_NOT_FOUND",
+      message: `File not found: ${options.file}`,
+      fix: "Pass a path to an existing file: graft asset put <file> [key].",
+      details: { file: options.file }
+    });
+  }
+  let storage;
+  try {
+    storage = createStorage(storageConfigFromEnv());
+  } catch (error) {
+    throw new GraftError({
+      code: "ENV_VAR_MISSING",
+      message: error instanceof Error ? error.message : String(error),
+      fix: "Set S3_ENDPOINT, S3_ACCESS_KEY, S3_SECRET_KEY, and S3_BUCKET in the project's .env (any parent directory works).",
+      details: { variables: ["S3_ENDPOINT", "S3_ACCESS_KEY", "S3_SECRET_KEY", "S3_BUCKET"] }
+    });
+  }
+  const key = options.key ?? defaultKeyFor(options.file);
+  const contentType = contentTypeFor(options.file);
+  await storage.put(key, body, contentType);
+  return { key, contentType, bytes: body.byteLength };
+}
+export {
+  assetPutCommand,
+  contentTypeFor,
+  defaultKeyFor
+};

package/dist/branch-HRG46YIL.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import {
+  loadProjectEnv,
+  requireDatabaseUrl
+} from "./chunk-BUPFXTUG.js";
+
+// src/commands/branch.ts
+import { GraftError } from "@usegraft/contracts";
+async function branchListCommand(options) {
+  loadProjectEnv(options.cwd);
+  const url = requireDatabaseUrl();
+  const { createDb, listBranches } = await import("@usegraft/db");
+  const handle = createDb(url);
+  try {
+    return await listBranches(handle.db);
+  } finally {
+    await handle.close();
+  }
+}
+async function branchCreateCommand(options) {
+  const backend = options.backend ?? "overlay";
+  if (backend !== "overlay" && backend !== "neon") {
+    throw new GraftError({
+      code: "BRANCH_INVALID",
+      message: `Unknown branch backend "${backend}".`,
+      fix: "Use --backend overlay (default; shared DB, instant) or --backend neon (physical fork; needs NEON_API_KEY + GRAFT_NEON_PROJECT_ID).",
+      details: { backend }
+    });
+  }
+  loadProjectEnv(options.cwd);
+  const url = requireDatabaseUrl();
+  const db = await import("@usegraft/db");
+  const handle = db.createDb(url);
+  try {
+    if (backend === "neon") {
+      const config = db.neonConfigFromEnv();
+      return await db.createNeonBranch(
+        handle.db,
+        { name: options.name, from: options.from, databaseUrl: url },
+        config
+      );
+    }
+    return await db.createBranch(handle.db, { name: options.name, from: options.from });
+  } finally {
+    await handle.close();
+  }
+}
+async function branchDropCommand(options) {
+  loadProjectEnv(options.cwd);
+  const url = requireDatabaseUrl();
+  const db = await import("@usegraft/db");
+  const handle = db.createDb(url);
+  try {
+    const meta = await db.getBranch(handle.db, options.name);
+    if (meta.backend === "neon") {
+      await db.dropNeonBranch(handle.db, options.name, db.neonConfigFromEnv());
+      return { backend: "neon" };
+    }
+    const result = await db.dropBranch(handle.db, options.name, { purgeRows: true });
+    return { ...result, backend: "overlay" };
+  } finally {
+    await handle.close();
+  }
+}
+function formatBranch(branch) {
+  const parent = branch.parent ? ` \u2190 ${branch.parent}` : " (root)";
+  const backend = branch.backend === "neon" && branch.endpointHost ? `neon @ ${branch.endpointHost}` : branch.backend;
+  return `${branch.name}${parent}  [${backend}, ${branch.status}, created ${branch.createdAt.toISOString().slice(0, 10)}]`;
+}
+export {
+  branchCreateCommand,
+  branchDropCommand,
+  branchListCommand,
+  formatBranch
+};

package/dist/chunk-BUPFXTUG.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+
+// src/config.ts
+import { existsSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { GraftError } from "@usegraft/contracts";
+import { createJiti } from "jiti";
+var CONFIG_FILENAMES = [
+  "graft.config.ts",
+  "graft.config.mts",
+  "graft.config.js",
+  "graft.config.mjs"
+];
+function findConfig(cwd) {
+  let dir = resolve(cwd);
+  for (; ; ) {
+    for (const name of CONFIG_FILENAMES) {
+      const candidate = join(dir, name);
+      if (existsSync(candidate)) return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new GraftError({
+    code: "CONFIG_NOT_FOUND",
+    message: `No graft.config.{ts,js} found in ${resolve(cwd)} or any parent directory.`,
+    fix: "cd into a Graft project, or scaffold one here with `graft init`."
+  });
+}
+function isCollection(value) {
+  return typeof value === "object" && value !== null && typeof value.name === "string" && typeof value.describe === "function" && "schema" in value;
+}
+function isFunction(value) {
+  return typeof value === "object" && value !== null && typeof value.name === "string" && typeof value.describe === "function" && typeof value.handler === "function" && "schema" in value;
+}
+async function loadConfig(configPath) {
+  const jiti = createJiti(configPath, { moduleCache: false });
+  let mod;
+  try {
+    mod = await jiti.import(configPath);
+  } catch (error) {
+    throw new GraftError({
+      code: "CONFIG_INVALID",
+      message: `Failed to load ${configPath}: ${error instanceof Error ? error.message : String(error)}`,
+      fix: "Fix the error in graft.config.ts \u2014 it must be importable and export `collections` (a record of defineCollection results)."
+    });
+  }
+  const collections = mod.collections;
+  if (typeof collections !== "object" || collections === null || Array.isArray(collections)) {
+    throw new GraftError({
+      code: "CONFIG_INVALID",
+      message: `${configPath} does not export a \`collections\` record.`,
+      fix: 'Add `export const collections = { \u2026 }` where each value is a defineCollection result from "@usegraft/core".'
+    });
+  }
+  const entries = Object.entries(collections);
+  if (entries.length === 0) {
+    throw new GraftError({
+      code: "CONFIG_INVALID",
+      message: `${configPath} exports an empty \`collections\` record.`,
+      fix: "Define at least one collection with defineCollection and include it in the exported `collections`."
+    });
+  }
+  for (const [key, value] of entries) {
+    if (!isCollection(value)) {
+      throw new GraftError({
+        code: "CONFIG_INVALID",
+        message: `collections.${key} in ${configPath} is not a collection.`,
+        fix: `Create it with defineCollection from "@usegraft/core" (it must have a name, a schema, and describe()).`,
+        details: { key }
+      });
+    }
+  }
+  let functions = {};
+  if (mod.functions !== void 0) {
+    if (typeof mod.functions !== "object" || mod.functions === null || Array.isArray(mod.functions)) {
+      throw new GraftError({
+        code: "CONFIG_INVALID",
+        message: `${configPath} exports \`functions\` but it is not a record.`,
+        fix: "Export `functions` as a record of defineFunction results, e.g. `export const functions = { pageStats }`, or omit the export."
+      });
+    }
+    const fnEntries = Object.entries(mod.functions);
+    for (const [key, value] of fnEntries) {
+      if (!isFunction(value)) {
+        throw new GraftError({
+          code: "CONFIG_INVALID",
+          message: `functions.${key} in ${configPath} is not a function.`,
+          fix: `Create it with defineFunction from "@usegraft/core" (it must have a name, a schema, a handler, and describe()).`,
+          details: { key }
+        });
+      }
+    }
+    functions = mod.functions;
+  }
+  const projectDir = dirname(configPath);
+  const index = parseIndexConfig(mod.index, projectDir, configPath);
+  assertStaticSupports(index, collections, functions, configPath);
+  const contentDirSetting = typeof mod.contentDir === "string" ? mod.contentDir : "content";
+  const migrationsDirSetting = typeof mod.migrationsDir === "string" ? mod.migrationsDir : "migrations";
+  return {
+    configPath,
+    projectDir,
+    contentDir: resolve(projectDir, contentDirSetting),
+    migrationsDir: resolve(projectDir, migrationsDirSetting),
+    index,
+    collections,
+    functions
+  };
+}
+function assertStaticSupports(index, collections, functions, configPath) {
+  if (index.driver !== "static") return;
+  const dbCollections = Object.values(collections).filter((collection) => collection.authority === "db-authoritative").map((collection) => collection.name);
+  const functionNames = Object.keys(functions);
+  if (dbCollections.length === 0 && functionNames.length === 0) return;
+  const needs = [
+    dbCollections.length > 0 ? `db-authoritative collection(s) ${dbCollections.map((n) => `"${n}"`).join(", ")}` : "",
+    functionNames.length > 0 ? `typed function(s) ${functionNames.map((n) => `"${n}"`).join(", ")}` : ""
+  ].filter(Boolean);
+  throw new GraftError({
+    code: "NEEDS_DATABASE",
+    message: `${configPath} uses the static index, but declares ${needs.join(" and ")} \u2014 those live in Postgres, not in the compiled artifact.`,
+    fix: 'Upgrade this project to the Postgres tier: set DATABASE_URL in .env, change graft.config to `export const index = "postgres"`, run `graft db migrate`, then `graft compile`. To stay service-free instead, remove the db-authoritative collections and functions (a `graft add` primitive that brought them can be deleted from graft/).',
+    details: { dbCollections, functions: functionNames }
+  });
+}
+var STATIC_INDEX_DEFAULT = ".graft/index.db";
+function parseIndexConfig(value, projectDir, configPath) {
+  if (value === void 0 || value === "postgres") return { driver: "postgres" };
+  if (value === "static") {
+    return { driver: "static", path: resolve(projectDir, STATIC_INDEX_DEFAULT) };
+  }
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    const driver = value.driver;
+    const path = value.path;
+    if (driver === "postgres") return { driver: "postgres" };
+    if (driver === "static" && (path === void 0 || typeof path === "string")) {
+      return { driver: "static", path: resolve(projectDir, path ?? STATIC_INDEX_DEFAULT) };
+    }
+  }
+  throw new GraftError({
+    code: "CONFIG_INVALID",
+    message: `${configPath} exports an invalid \`index\` setting.`,
+    fix: `Use \`export const index = "static"\` (SQLite artifact, zero services), \`"postgres"\` (DATABASE_URL \u2014 the default when omitted), or { driver: "static", path: "\u2026" }.`,
+    details: { index: value }
+  });
+}
+function loadProjectEnv(startDir) {
+  let dir = resolve(startDir);
+  for (; ; ) {
+    const candidate = join(dir, ".env");
+    if (existsSync(candidate)) {
+      try {
+        process.loadEnvFile(candidate);
+      } catch {
+      }
+      return;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return;
+    dir = parent;
+  }
+}
+function requireDatabaseUrl() {
+  const url = process.env.DATABASE_URL;
+  if (url) return url;
+  throw new GraftError({
+    code: "ENV_VAR_MISSING",
+    message: "DATABASE_URL is not set.",
+    fix: "Add DATABASE_URL=postgres://\u2026 to the project's .env (any parent directory works) or export it in the environment.",
+    details: { variable: "DATABASE_URL" }
+  });
+}
+
+export {
+  CONFIG_FILENAMES,
+  findConfig,
+  loadConfig,
+  loadProjectEnv,
+  requireDatabaseUrl
+};

package/dist/chunk-GPA66AP5.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+// src/report.ts
+function printGraftError(error) {
+  console.error(`error ${error.code}: ${error.message}`);
+  if (error.fix) console.error(`  fix: ${error.fix}`);
+  if (error.details) console.error(`  details: ${JSON.stringify(error.details)}`);
+}
+function formatCompileResult(result) {
+  const { added, changed, removed, unchanged } = result.changes;
+  const lines = [
+    `Compiled ${result.count} doc(s) @ ${result.gitSha?.slice(0, 7) ?? "no-git"}: +${added.length} added, ~${changed.length} changed, -${removed.length} removed, ${unchanged} unchanged`
+  ];
+  for (const key of [...added, ...changed]) lines.push(`  upserted ${key}`);
+  for (const key of removed) lines.push(`  removed  ${key}`);
+  return lines.join("\n");
+}
+
+export {
+  printGraftError,
+  formatCompileResult
+};

package/dist/chunk-KZ3FDWUK.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import {
+  formatCompileResult
+} from "./chunk-GPA66AP5.js";
+import {
+  findConfig,
+  loadConfig,
+  loadProjectEnv,
+  requireDatabaseUrl
+} from "./chunk-BUPFXTUG.js";
+
+// src/commands/compile.ts
+import { GraftError } from "@usegraft/contracts";
+function assertNoStaticBranch(branchId) {
+  if (branchId === void 0 || branchId === "main") return;
+  throw new GraftError({
+    code: "NEEDS_DATABASE",
+    message: `--branch ${branchId} needs the Postgres index: this project runs in static mode, where a "branch" is just your git branch.`,
+    fix: `Check out the git branch and compile (each checkout builds its own artifact), or upgrade to Postgres for DB branching: set DATABASE_URL and \`export const index = "postgres"\` in graft.config.`,
+    details: { branchId }
+  });
+}
+async function compileCommand(options) {
+  loadProjectEnv(options.cwd);
+  const config = await loadConfig(findConfig(options.cwd));
+  if (config.index.driver === "static") {
+    assertNoStaticBranch(options.branchId);
+    const { compileStatic } = await import("@usegraft/compiler");
+    const result = await compileStatic({
+      contentDir: config.contentDir,
+      collections: config.collections,
+      indexPath: config.index.path
+    });
+    console.log(formatCompileResult(result));
+    return result;
+  }
+  const url = requireDatabaseUrl();
+  const [{ compile }, { createDb, resolveBranchHandle, scopeWriteBranch }] = await Promise.all([
+    import("@usegraft/compiler"),
+    import("@usegraft/db")
+  ]);
+  const control = createDb(url);
+  try {
+    const branch = await resolveBranchHandle(control.db, options.branchId ?? "main", {
+      databaseUrl: url
+    });
+    try {
+      if (branch.scope.kind === "physical") {
+        console.log(`neon branch "${branch.name}" \u2014 compiling into its own database`);
+      }
+      const result = await compile({
+        db: branch.db,
+        contentDir: config.contentDir,
+        collections: config.collections,
+        branchId: scopeWriteBranch(branch.scope),
+        pruneUnknown: options.pruneUnknown
+      });
+      console.log(formatCompileResult(result));
+      return result;
+    } finally {
+      await branch.close();
+    }
+  } finally {
+    await control.close();
+  }
+}
+
+export {
+  assertNoStaticBranch,
+  compileCommand
+};