@straiffi/archon 1.0.0

package/README.md

@@ -0,0 +1,224 @@
+# Archon
+
+A ticket-driven interface for AI-assisted code automation. Create tickets, plan features, then let an AI agent (Claude or OpenCode) implement them in isolated git worktrees.
+
+## Install
+
+Archon ships as a global npm package:
+
+```bash
+npm install -g @straiffi/archon
+```
+
+Then start it with:
+
+```bash
+archon
+```
+
+Archon will:
+
+1. start the backend and frontend as one local process
+2. serve the UI and API from the same origin
+3. open your default browser automatically
+4. stay attached until you press `Ctrl+C`
+
+Typical startup output:
+
+```text
+Archon running at http://localhost:43110
+Press Ctrl+C to stop.
+```
+
+Archon starts on port `43110` by default and scans upward if that port is already in use.
+
+### Update
+
+```bash
+archon update
+```
+
+### Supported platforms
+
+V1 targets macOS and Linux first.
+
+## External tool prerequisites
+
+Archon does not bundle external developer tools.
+
+Required or commonly expected tools:
+
+| Tool | Why it matters |
+| --- | --- |
+| `git` | Required for project repositories, worktrees, diffing, and commit operations |
+| `opencode` | Required for OpenCode plan/build/chat/review workflows |
+| `claude` | Required for Claude-backed workflows |
+| `gh` | Required for GitHub PR and review integration |
+
+If one of the optional AI tools is missing, Archon should still start, but features that depend on that binary will return actionable errors.
+
+## How it works
+
+Tickets move through three states:
+
+1. **Plan** — write a title and description for the feature or task
+2. **Build** — the server spawns your configured AI tool in a new git worktree on a dedicated branch; real-time logs stream back to the UI
+3. **Review** — an agent conducts a code review and fixes any issues found
+
+The frontend is a React kanban board. The backend is an Express server with a SQLite database and Socket.io for live status updates.
+
+## Development
+
+For normal source development, use the repo checkout workflow instead of the packaged CLI.
+
+Install dependencies from the repository root:
+
+```bash
+npm install
+```
+
+Start dev mode:
+
+```bash
+npm run start:dev
+```
+
+`npm run start:dev` is the primary local development command. It keeps the Express server and Vite frontend as separate processes and configures the dev database plus API base URL overrides for you.
+
+Other useful commands:
+
+```bash
+npm run build
+npm test
+npm run smoke:package
+```
+
+`npm run smoke:package` builds the package, installs the packed tarball into a temporary npm prefix, runs `archon --version`, starts `archon --no-open`, fetches the app shell and an API route, then shuts it down.
+
+## Project Setup
+
+After Archon starts, create a project from the UI:
+
+1. Click `Create project`
+2. Enter a project name and repository path
+3. Optionally click `Auto-config` to inspect top-level repo files and fill any empty setup, service, or worktree sync settings
+4. Optionally open `Advanced settings` to review or edit setup, service, worktree sync, and IDE settings
+5. Save the project, select it in the project switcher, and create tickets inside that project
+
+## Project configuration
+
+Archon stores repository and run settings per project in its database. Use the project form in the UI to configure each project.
+
+### Required fields
+
+| Field | What to enter |
+|-------|---------------|
+| `Project name` | The label shown in the project switcher, such as `Platform API` or `Marketing Site` |
+| `Repository path` | Any path inside the target git repository; Archon resolves it to the repo root before saving |
+
+`Auto-config` is available in both the create and edit project modals. It uses the currently selected global tool, reads only top-level README/config files, and fills only empty `Setup commands`, `Services`, and `Worktree sync` sections. It never changes `IDE command`.
+
+### Advanced fields
+
+| Field | Guidance |
+|-------|----------|
+| `Setup commands` | Optional newline-separated commands that run inside the new worktree before any services start. Use this for dependency install, code generation, or other one-time setup such as `pnpm install` or `pnpm db:generate`. |
+| `Worktree sync` | Optional file sync rules that run only when Archon creates a worktree for the first time. Each entry can either copy a file or directory into the new worktree, or symlink back to the project repo. |
+| `Services` | Optional background processes to launch after setup completes. Each service needs a command, and can also include a `cwd`. |
+| `cwd` | Optional working directory for a service, relative to the worktree root. For example, use `client` for a frontend dev server or `server` for an API process. Leave it blank to run from the worktree root. |
+| `IDE command` | Optional command to open the finished worktree in your editor after services start, such as `code --reuse-window` or `idea`. |
+
+Worktree sync entries are stored as `{ source, target?, mode }` objects. `source` is required, `target` is optional and defaults to the same path, and `mode` is either `copy` or `symlink`.
+
+Service entries are stored as `{ cmd, cwd }` objects. `cmd` is required, while `cwd` is optional.
+
+### Example project setup
+
+```text
+Project name: My App
+Repository path: /Users/you/projects/my-app
+Setup commands:
+pnpm install
+pnpm db:generate
+
+Worktree sync:
+- source: node_modules
+  mode: symlink
+- source: .env
+  mode: copy
+
+Services:
+- cmd: pnpm dev
+  cwd: client
+- cmd: pnpm dev
+  cwd: server
+
+IDE command: code --reuse-window
+```
+
+Each ticket gets its own worktree and branch derived from the ticket title, using the active project's repository settings. Archon reuses an existing local branch when one already exists; otherwise it creates a new branch for the worktree.
+
+## Data And Migration
+
+Archon keeps runtime state out of the installed package tree.
+
+Default database locations:
+
+| Platform | Default path |
+| --- | --- |
+| macOS | `~/Library/Application Support/Archon/archon.db` |
+| Linux | `~/.local/share/archon/archon.db` |
+
+You can override the database location with `DB_PATH`.
+
+### Migrating from an existing dev database
+
+Older local development runs may already have data in one of these files:
+
+- `server/archon-dev.db`
+- `server/archon.db`
+
+Recommended manual migration flow:
+
+1. Stop all Archon dev and production processes.
+2. Back up the source database and any current production database.
+3. Create the production app-data directory if it does not exist.
+4. Copy the chosen development database to the production database path.
+5. If SQLite sidecar files such as `-wal` or `-shm` exist, only copy them while Archon is fully stopped.
+6. Start Archon normally and let its startup schema checks apply any missing migrations.
+
+If you want to run production Archon against an existing database temporarily, launch it with:
+
+```bash
+DB_PATH=/path/to/archon-dev.db archon
+```
+
+## Release Process
+
+Archon uses a manual GitHub Actions release workflow.
+
+### GitHub setup
+
+1. Publish the npm package scope or package name from the npm account or organization that owns `@straiffi/archon`.
+2. Add an `NPM_TOKEN` repository secret in GitHub with publish access to that package.
+3. Run the `Release` workflow from the `main` branch.
+4. Choose one of `patch`, `minor`, or `major` for `release_type`.
+
+The workflow will:
+
+1. install dependencies
+2. run type checks, lint, tests, build, tarball validation, and packaged-install smoke checks
+3. run `npm version <release_type>`
+4. publish with `npm publish --access public`
+5. push the version commit and git tag back to GitHub
+
+### Local release dry run
+
+Before running the workflow, you can validate the release path locally with:
+
+```bash
+npm install
+npm run build
+npm run smoke:package
+npm pack --dry-run
+```

package/dist/cli.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+
+import { createServer } from 'node:net'
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const CURRENT_FILE_PATH = fileURLToPath(import.meta.url)
+const CURRENT_DIRECTORY = dirname(CURRENT_FILE_PATH)
+const PACKAGE_JSON_PATH = resolve(CURRENT_DIRECTORY, '../package.json')
+const DIST_SERVER_ENTRY_PATH = resolve(CURRENT_DIRECTORY, './server/index.js')
+const DEFAULT_PORT = 43110
+const PACKAGE_NAME = '@straiffi/archon'
+
+const readPackageVersion = () => {
+  try {
+    const packageJson = JSON.parse(readFileSync(PACKAGE_JSON_PATH, 'utf8'))
+    return typeof packageJson?.version === 'string' ? packageJson.version : '0.0.0'
+  } catch {
+    return '0.0.0'
+  }
+}
+
+const printUsage = () => {
+  console.log(`Usage: archon [--port <port>] [--no-open]\n       archon update\n       archon --version`)
+}
+
+const parsePort = (value) => {
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+    throw new Error(`Invalid port: ${value}`)
+  }
+
+  return parsed
+}
+
+const parseArgs = (argv) => {
+  let command = 'start'
+  let port = DEFAULT_PORT
+  let shouldOpenBrowser = true
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index]
+
+    if (argument === 'update') {
+      command = 'update'
+      continue
+    }
+
+    if (argument === '--version' || argument === '-v') {
+      command = 'version'
+      continue
+    }
+
+    if (argument === '--help' || argument === '-h') {
+      command = 'help'
+      continue
+    }
+
+    if (argument === '--no-open') {
+      shouldOpenBrowser = false
+      continue
+    }
+
+    if (argument === '--port') {
+      const nextValue = argv[index + 1]
+      if (!nextValue) {
+        throw new Error('--port requires a value')
+      }
+
+      port = parsePort(nextValue)
+      index += 1
+      continue
+    }
+
+    throw new Error(`Unknown argument: ${argument}`)
+  }
+
+  return {
+    command,
+    port,
+    shouldOpenBrowser,
+  }
+}
+
+const canUsePort = (port) => {
+  return new Promise(resolvePromise => {
+    const probeServer = createServer()
+
+    probeServer.once('error', () => {
+      resolvePromise(false)
+    })
+
+    probeServer.once('listening', () => {
+      probeServer.close(() => {
+        resolvePromise(true)
+      })
+    })
+
+    probeServer.listen(port, '127.0.0.1')
+  })
+}
+
+const findAvailablePort = async (startingPort) => {
+  let port = startingPort
+
+  while (!(await canUsePort(port))) {
+    port += 1
+  }
+
+  return port
+}
+
+const openBrowser = (url) => {
+  const openCommand = process.platform === 'darwin'
+    ? ['open', [url]]
+    : process.platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', url]]
+      : ['xdg-open', [url]]
+
+  const [command, args] = openCommand
+
+  return new Promise(resolvePromise => {
+    const child = spawn(command, args, {
+      stdio: 'ignore',
+      detached: true,
+    })
+
+    child.on('error', () => resolvePromise(false))
+    child.unref()
+    resolvePromise(true)
+  })
+}
+
+const runUpdate = () => {
+  return new Promise(resolvePromise => {
+    const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+    const child = spawn(npmCommand, ['install', '-g', `${PACKAGE_NAME}@latest`], {
+      stdio: 'inherit',
+      env: process.env,
+    })
+
+    child.on('error', () => {
+      console.error(`Update failed. Run: npm install -g ${PACKAGE_NAME}@latest`)
+      resolvePromise(1)
+    })
+
+    child.on('exit', code => {
+      if (code && code !== 0) {
+        console.error(`Update failed. Run: npm install -g ${PACKAGE_NAME}@latest`)
+      }
+
+      resolvePromise(code ?? 0)
+    })
+  })
+}
+
+const startArchon = async ({ port, shouldOpenBrowser }) => {
+  if (!existsSync(DIST_SERVER_ENTRY_PATH)) {
+    throw new Error('Archon is not built yet. Run `npm run build` before starting the packaged runtime from a source checkout.')
+  }
+
+  process.env.PORT = String(await findAvailablePort(port))
+
+  const serverModule = await import(pathToFileURL(DIST_SERVER_ENTRY_PATH).href)
+  if (typeof serverModule.registerShutdownHandlers === 'function') {
+    serverModule.registerShutdownHandlers()
+  }
+
+  const result = await serverModule.startServer({ port: Number(process.env.PORT) })
+
+  console.log(`Archon running at ${result.url}`)
+  console.log('Press Ctrl+C to stop.')
+
+  if (shouldOpenBrowser) {
+    const opened = await openBrowser(result.url)
+    if (!opened) {
+      console.warn(`Unable to open a browser automatically. Open ${result.url} manually.`)
+    }
+  }
+}
+
+const main = async () => {
+  let parsedArgs
+
+  try {
+    parsedArgs = parseArgs(process.argv.slice(2))
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    printUsage()
+    process.exit(1)
+  }
+
+  if (parsedArgs.command === 'help') {
+    printUsage()
+    return
+  }
+
+  if (parsedArgs.command === 'version') {
+    console.log(readPackageVersion())
+    return
+  }
+
+  if (parsedArgs.command === 'update') {
+    process.exitCode = await runUpdate()
+    return
+  }
+
+  await startArchon(parsedArgs)
+}
+
+void main().catch(error => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+})