@usegraft/cli 0.0.0-canary-20260831153011

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/README.md

@@ -0,0 +1,64 @@
+# @usegraft/cli
+
+> The `graft` command. Scaffold a project, compile authored content, serve the runtime, split your database credentials.
+
+Part of [Graft](https://github.com/AndersonDesign1/graft), a CMS built so an AI agent is the primary operator.
+
+## Install
+
+```bash
+npm i -D @usegraft/cli
+# or run it without installing
+npx @usegraft/cli init
+```
+
+Once installed, the command is `graft`. Run it without installing under the
+full package name: the bare name `graft` on npm belongs to an unrelated
+package, so `npx graft` fetches the wrong thing.
+
+## Quickstart, with no database
+
+A content project needs no services at all. `graft compile` writes the index to a SQLite artifact your app reads embedded.
+
+```bash
+npx @usegraft/cli init      # scaffolds graft.config.ts, content/, llms.txt
+npx @usegraft/cli compile   # → .graft/index.db
+```
+
+Move to Postgres by setting `DATABASE_URL` and changing one line in `graft.config.ts`:
+
+```ts
+export const index = "postgres";
+```
+
+## Commands
+
+| Command                        | Does                                                                                           |
+| ------------------------------ | ---------------------------------------------------------------------------------------------- |
+| `graft init`                   | Scaffold a project                                                                             |
+| `graft compile`                | Validate authored MDX and project it into the index                                            |
+| `graft dev`                    | Recompile on save                                                                              |
+| `graft serve`                  | Run the headless runtime: typed functions, MCP, authored-content reads, `/healthz`             |
+| `graft studio`                 | Open the optional editing UI                                                                   |
+| `graft mcp`                    | Serve MCP on stdio, for `.mcp.json`                                                            |
+| `graft add <item>`             | Copy a registry primitive into your repo, shadcn-style                                         |
+| `graft approve <id>`           | Decide a pending approval. Operator credential only                                            |
+| `graft harden <role>`          | Grant a Postgres role exactly what a deployment needs, and nothing that can decide an approval |
+| `graft branch` / `graft merge` | Copy-on-write content branches                                                                 |
+| `graft migrate`                | Run content codemods when the schema changes                                                   |
+
+Run `graft <command> --help` for flags.
+
+## Two credentials
+
+`graft harden` splits the operator credential from the runtime one. The runtime can serve, project content, and request approvals. It can never decide one, and Postgres enforces that rather than the application.
+
+```bash
+graft harden graft_runtime
+# deploy with the runtime role's URL as DATABASE_URL
+# keep the operator URL for compile, migrate, merge and approve
+```
+
+---
+
+MIT. [Repository](https://github.com/AndersonDesign1/graft) · [Changelog](https://github.com/AndersonDesign1/graft/blob/main/packages/cli/CHANGELOG.md) · [Security policy](https://github.com/AndersonDesign1/graft/blob/main/SECURITY.md)

package/dist/add-ASXTMYCX.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import {
+  findConfig
+} from "./chunk-2NH6KYTL.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-OEEQQN75.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import {
+  approvalsListCommand,
+  decideCommand,
+  formatApproval,
+  operatorName
+} from "./chunk-3CP4IY73.js";
+import "./chunk-2NH6KYTL.js";
+export {
+  approvalsListCommand,
+  decideCommand,
+  formatApproval,
+  operatorName
+};

package/dist/asset-DMNX5JBZ.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import {
+  loadProjectEnv
+} from "./chunk-2NH6KYTL.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-IDY42TAV.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import {
+  loadProjectEnv,
+  requireDatabaseUrl
+} from "./chunk-2NH6KYTL.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-2NH6KYTL.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+
+// src/config.ts
+import { existsSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { GraftError, STATIC_INDEX_DEFAULT_PATH } 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 mdxTrust = parseMdxTrust(mod.mdxTrust, 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,
+    mdxTrust
+  };
+}
+function parseMdxTrust(value, configPath) {
+  if (value === void 0) return "restricted";
+  if (value === "restricted" || value === "full") return value;
+  throw new GraftError({
+    code: "CONFIG_INVALID",
+    message: `${configPath} exports \`mdxTrust\` as ${JSON.stringify(value)}, which is not "restricted" or "full".`,
+    fix: 'Export `mdxTrust = "restricted"` (the default: `{\u2026}` expressions and `import` are refused in authored bodies) or `mdxTrust = "full"` (every author has commit access, so code review is the control). Omit the export to keep the default.',
+    details: { mdxTrust: value }
+  });
+}
+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 }
+  });
+}
+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_PATH) };
+  }
+  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_PATH) };
+    }
+  }
+  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-3CP4IY73.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import {
+  loadProjectEnv,
+  requireDatabaseUrl
+} from "./chunk-2NH6KYTL.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, {
+      kind: "human",
+      id: 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 {
+  operatorName,
+  approvalsListCommand,
+  decideCommand,
+  formatApproval
+};