Integrate the initial First Draft CLI

.gitattributes

@@ -0,0 +1,2 @@
+* text=auto eol=lf
+bin/*.js text eol=lf

.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  compatibility:
+    name: Node 22.0 / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    # Node 22.0's npm.ps1 is broken on Windows; Bash selects the bundled npm shell shim instead.
+    # https://github.com/nodejs/node/issues/52682
+    defaults:
+      run:
+        shell: bash
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 22.0.0
+          package-manager-cache: false
+      - run: npm ci --omit=dev --ignore-scripts
+      - run: npm test
+      - run: npm run pack:check
+      - run: npm run pack:smoke
+
+  quality:
+    name: Node 24 quality
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24.18.0
+          package-manager-cache: false
+      - run: npm ci --ignore-scripts
+      - run: npm audit
+      - run: npm run check

.gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+coverage/
+node_modules/
+tmp/
+*.tgz

.npmrc

@@ -0,0 +1,5 @@
+audit=true
+fund=false
+ignore-scripts=true
+package-lock=true
+save-exact=true

.tool-versions

@@ -0,0 +1 @@
+nodejs 24.18.0

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 First Draft contributors
+
+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.

README.md

@@ -0,0 +1,80 @@
+# First Draft CLI
+
+`firstdraft` is the command-line client for [First Draft](https://github.com/firstdraft/firstdraft). It is being
+built for agents that author and review Foundation Plans with their users.
+
+The package is not released yet. This repository contains the auditable command shell, local Foundation Plan
+initialization, subject identity generation, and conditional whole-document push; release behavior will arrive in
+reviewed increments.
+
+## Requirements
+
+- Running the CLI: Node.js 22.0.0 or newer
+- Working on this repository: Node.js 24.18.0 (pinned in `.tool-versions`)
+
+## Development
+
+```sh
+npm ci
+npm run check
+npm run pack:check
+```
+
+## Start a Foundation Plan
+
+From the project that the Plan describes:
+
+```sh
+firstdraft plan init --application-key oscar_party --name "Oscar Party"
+```
+
+This creates an empty `sketch/0.19` Plan and client-generated Project ID under `.firstdraft/`. A nested ignore file
+keeps that local scratch area out of Git without changing the project's own `.gitignore`. Initialization makes no
+network request and refuses to replace an existing `.firstdraft` path.
+
+## Add Foundation Plan subjects
+
+Generate an identity before adding each new independently mutable authored subject:
+
+```sh
+firstdraft plan subject-id
+```
+
+The command prints one UUIDv7 for the subject's `subject_uuid`. It does not read or modify the Plan, reserve the
+value, or make a network request. Preserve that UUID when renaming the subject or moving it to a different semantic
+owner without changing its kind. Use a new UUID for a replacement concept. Readable keys and paths may change and
+remain the document's links; the UUID preserves continuity between complete-document pushes.
+
+## Push a Foundation Plan
+
+From the initialized project:
+
+```sh
+firstdraft plan push
+```
+
+The command sends the exact bytes in `.firstdraft/foundation-plan.json`. The first push conditionally creates the
+Project; later pushes replay the complete ETag saved in `.firstdraft/state.json` so a stale writer cannot replace a
+newer Plan. Successful responses and server diagnostics are printed as JSON for an agent to inspect.
+
+The initial API origin defaults to `https://firstdraft.com`. Set `FIRSTDRAFT_API_URL` to use another HTTPS origin
+or a loopback HTTP development server. The first successful push pins the normalized origin in local state, and a
+later override must match it.
+
+If a failure happens after sending the request, the CLI reports that the outcome may be ambiguous and leaves local
+state unchanged. It never constructs an ETag from the Plan digest or trusts an ETag from a response it could not
+fully verify. Until First Draft has a read or reconciliation endpoint, an accepted request whose response cannot be
+verified may require manual recovery. If a verified response cannot replace local state, preserve the printed
+recovery state; an adjacent `.tmp` file may contain the same private recovery copy.
+
+## Trust model
+
+- The published CLI will run the reviewed JavaScript source directly, without generated or bundled code.
+- The CLI has no runtime dependencies, install scripts, telemetry, update checks, or network activity except an
+  explicitly invoked API command.
+- Package contents are allowlisted and checked before release.
+- CI exercises the exact minimum Node.js version separately from current development tooling.
+- Public releases will use npm provenance after the first useful version bootstraps trusted publishing.
+
+Security issues should follow the
+[private reporting instructions](https://github.com/firstdraft/cli/security/advisories/new).

SECURITY.md

@@ -0,0 +1,8 @@
+# Security
+
+Please report suspected vulnerabilities through a
+[private GitHub security advisory](https://github.com/firstdraft/cli/security/advisories/new). Do not include
+sensitive details in a public Issue.
+
+The CLI has not released a supported version yet. This policy will name supported release lines before the first
+public package is published.

bin/firstdraft.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+import { run } from "../src/cli.js";
+
+process.stdout.on("error", handleStreamError);
+process.stderr.on("error", handleStreamError);
+
+process.exitCode = await run({
+  argv: process.argv.slice(2),
+  stdout: process.stdout,
+  stderr: process.stderr,
+});
+
+/** @param {Error} error */
+function handleStreamError(error) {
+  if ("code" in error && error.code === "EPIPE") return;
+
+  throw error;
+}

eslint.config.js

@@ -0,0 +1,25 @@
+import js from "@eslint/js";
+import globals from "globals";
+
+export default [
+  {
+    ignores: ["node_modules/", "tmp/"],
+  },
+  js.configs.recommended,
+  {
+    files: ["**/*.js"],
+    languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      globals: globals.nodeBuiltin,
+    },
+    linterOptions: {
+      reportUnusedDisableDirectives: "error",
+    },
+    rules: {
+      "no-constant-binary-expression": "error",
+      "no-duplicate-imports": "error",
+      "no-promise-executor-return": "error",
+    },
+  },
+];

jsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": true,
+    "lib": ["ES2023"],
+    "maxNodeModuleJsDepth": 0,
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noEmit": true,
+    "noImplicitReturns": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": false,
+    "strict": true,
+    "target": "ES2023",
+    "types": ["node"],
+    "verbatimModuleSyntax": true
+  },
+  "include": [
+    "bin/**/*.js",
+    "eslint.config.js",
+    "scripts/**/*.js",
+    "src/**/*.js",
+    "test/**/*.js"
+  ]
+}