firth 0.0.1

package/README.md

@@ -0,0 +1,76 @@
+# firth-cli
+
+> The runtime CLI for [Firth](https://github.com/firthdev/firth) — the cloud platform SDK for AI coding agents.
+
+**Status:** Pre-alpha. v0.0.1 ships only `firth init` (project scaffolding).
+
+This repo is the **L2 / CLI layer** of the Firth project. The companion repo [`firth`](https://github.com/firthdev/firth) holds the L1 / Knowledge layer (Skills, templates, runbooks, ARCHITECTURE.md).
+
+For the project's overall design and rationale, see [`firth/ARCHITECTURE.md`](https://github.com/firthdev/firth/blob/main/ARCHITECTURE.md). This README is just for the CLI itself.
+
+## Local development
+
+```bash
+# from this directory
+npm install
+
+# run the CLI in dev (no build step)
+npm run dev -- init
+
+# typecheck
+npm run typecheck
+
+# tests
+npm test
+
+# build a distributable
+npm run build
+
+# link into your shell so `firth` works globally during dev
+npm link
+firth init my-test-app
+```
+
+## Commands (current)
+
+### `firth init [name]`
+
+Scaffold a Firth project. Generates `firth.config.ts` and `firth.lock.json`.
+
+```bash
+# interactive
+firth init my-app
+
+# in current directory
+firth init .
+
+# non-interactive (agent-friendly): use defaults
+firth init my-app --yes
+
+# non-interactive with explicit overrides
+firth init my-app --frontend=nextjs --backend=hono --db=neon \
+  --frontend-host=vercel --backend-host=railway --yes
+```
+
+Defaults (when `--yes` is passed): Next.js + Hono + Neon Postgres + Vercel + Railway.
+
+## Commands (planned)
+
+- `firth deploy` — provision resources and push code across the stack.
+- `firth secrets set/get/list` — sync secrets across providers.
+- `firth logs [--service]` — tail logs.
+- `firth status` — current deployment + resource state.
+- `firth handoff` — generate a context dump for a fresh agent session.
+- `firth db migrate / db reset` — database lifecycle.
+
+## Design notes
+
+- **Thin orchestrator, not a wrapper.** Every command shells out to the official provider CLI/API; we never re-implement provider features.
+- **Agent-friendly errors.** Failures emit `ERROR / LIKELY CAUSE / SUGGESTED ACTIONS` so an agent loop can recover.
+- **Local state lives in the project.** `firth.config.ts` (declarative, hand-edited) + `firth.lock.json` (generated, holds resource IDs) — both committed.
+
+See [`firth/ARCHITECTURE.md`](https://github.com/firthdev/firth/blob/main/ARCHITECTURE.md) for the full rationale.
+
+## License
+
+MIT (planned).

package/dist/cli.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { defineCommand as defineCommand2, runMain } from "citty";
+
+// src/commands/init.ts
+import { defineCommand } from "citty";
+import * as p from "@clack/prompts";
+import { writeFile, mkdir } from "fs/promises";
+import { existsSync } from "fs";
+import { resolve, basename } from "path";
+var initCommand = defineCommand({
+  meta: {
+    name: "init",
+    description: "Scaffold Firth project files (firth.config.ts + firth.lock.json) in the target directory."
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Project directory (use '.' for current directory)",
+      required: false,
+      default: "."
+    },
+    yes: {
+      type: "boolean",
+      alias: "y",
+      description: "Skip all prompts; use defaults (Next.js + Hono + Neon + Vercel + Railway). Safe for non-interactive agent runs.",
+      default: false
+    },
+    frontend: {
+      type: "string",
+      description: "Frontend framework override (nextjs)"
+    },
+    backend: {
+      type: "string",
+      description: "Backend framework override (hono | express | none)"
+    },
+    db: {
+      type: "string",
+      description: "Database provider override (neon | none)"
+    },
+    "frontend-host": {
+      type: "string",
+      description: "Frontend host override (vercel | none)"
+    },
+    "backend-host": {
+      type: "string",
+      description: "Backend host override (railway | none)"
+    }
+  },
+  async run({ args }) {
+    const rawName = String(args.name);
+    const targetDir = resolve(process.cwd(), rawName);
+    const projectName = rawName === "." ? basename(targetDir) : basename(targetDir);
+    p.intro("firth init");
+    const configPath = resolve(targetDir, "firth.config.ts");
+    if (existsSync(configPath)) {
+      p.cancel(
+        [
+          "ERROR: firth.config.ts already exists.",
+          `LOCATION: ${configPath}`,
+          "SUGGESTED ACTIONS:",
+          "  1. Edit firth.config.ts by hand to change the stack.",
+          "  2. Or delete firth.config.ts and re-run `firth init`."
+        ].join("\n")
+      );
+      process.exit(1);
+    }
+    const stack = args.yes ? defaultStack() : await promptStack(args);
+    if (!stack) {
+      p.cancel("Cancelled.");
+      process.exit(0);
+    }
+    const config = { project: projectName, stack };
+    const lock = { version: 1, resources: {} };
+    if (!existsSync(targetDir)) {
+      await mkdir(targetDir, { recursive: true });
+    }
+    await writeFile(configPath, renderConfig(config), "utf8");
+    await writeFile(
+      resolve(targetDir, "firth.lock.json"),
+      JSON.stringify(lock, null, 2) + "\n",
+      "utf8"
+    );
+    p.outro(
+      [
+        `OK: wrote firth.config.ts and firth.lock.json to ${targetDir}`,
+        "",
+        "NEXT STEPS:",
+        "  1. Review firth.config.ts and adjust the stack if needed.",
+        "  2. Run `firth deploy` to provision and ship (coming soon)."
+      ].join("\n")
+    );
+  }
+});
+function defaultStack() {
+  return {
+    frontend: "nextjs",
+    backend: "hono",
+    db: "neon",
+    frontendHost: "vercel",
+    backendHost: "railway"
+  };
+}
+async function promptStack(args) {
+  const frontend = args.frontend ?? await p.select({
+    message: "Frontend framework?",
+    options: [{ value: "nextjs", label: "Next.js" }],
+    initialValue: "nextjs"
+  });
+  if (p.isCancel(frontend)) return null;
+  const backend = args.backend ?? await p.select({
+    message: "Backend framework?",
+    options: [
+      { value: "hono", label: "Hono (recommended)" },
+      { value: "express", label: "Express" },
+      { value: "none", label: "None (frontend-only)" }
+    ],
+    initialValue: "hono"
+  });
+  if (p.isCancel(backend)) return null;
+  const db = args.db ?? await p.select({
+    message: "Database?",
+    options: [
+      { value: "neon", label: "Neon Postgres" },
+      { value: "none", label: "None" }
+    ],
+    initialValue: "neon"
+  });
+  if (p.isCancel(db)) return null;
+  const frontendHost = args["frontend-host"] ?? await p.select({
+    message: "Frontend hosting?",
+    options: [
+      { value: "vercel", label: "Vercel" },
+      { value: "none", label: "Not yet" }
+    ],
+    initialValue: "vercel"
+  });
+  if (p.isCancel(frontendHost)) return null;
+  let backendHost;
+  if (backend === "none") {
+    backendHost = "none";
+  } else {
+    const result = args["backend-host"] ?? await p.select({
+      message: "Backend hosting?",
+      options: [
+        { value: "railway", label: "Railway" },
+        { value: "none", label: "Not yet" }
+      ],
+      initialValue: "railway"
+    });
+    if (p.isCancel(result)) return null;
+    backendHost = String(result);
+  }
+  return {
+    frontend: String(frontend),
+    backend: String(backend),
+    db: String(db),
+    frontendHost: String(frontendHost),
+    backendHost
+  };
+}
+function renderConfig(config) {
+  return `// firth.config.ts
+// Generated by \`firth init\`. Source-of-truth for this project's stack.
+// Hand-edit, then run \`firth deploy\` to apply changes.
+
+export default ${JSON.stringify(config, null, 2)};
+`;
+}
+
+// src/cli.ts
+var main = defineCommand2({
+  meta: {
+    name: "firth",
+    version: "0.0.1",
+    description: "Cloud platform SDK for AI coding agents."
+  },
+  subCommands: {
+    init: initCommand
+  }
+});
+runMain(main);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "firth",
+  "version": "0.0.1",
+  "description": "Cloud platform SDK for AI coding agents — scaffold, deploy, and operate cloud stacks alongside your AI coding agent.",
+  "type": "module",
+  "bin": {
+    "firth": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "cli",
+    "ai-agent",
+    "deploy",
+    "scaffold",
+    "vercel",
+    "railway",
+    "neon",
+    "firth"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "citty": "^0.1.6"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsup": "^8.0.2",
+    "tsx": "^4.7.1",
+    "typescript": "^5.4.0",
+    "vitest": "^1.4.0"
+  }
+}