spexcode 0.1.2 → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpexCode
+
+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/package.json

@@ -1,10 +1,12 @@
 {
   "name": "spexcode",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
   "license": "MIT",
-  "bin": { "spex": "spec-cli/bin/spex.mjs" },
+  "bin": {
+    "spex": "spec-cli/bin/spex.mjs"
+  },
   "files": [
     "spec-cli/src",
     "!spec-cli/src/**/*.test.ts",
@@ -18,7 +20,9 @@
     "spec-dashboard/dist",
     "README.md"
   ],
-  "engines": { "node": ">=22" },
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "api": "npm --prefix spec-cli run serve",
     "web": "npm --prefix spec-dashboard run dev",

package/spec-cli/src/harness.ts

@@ -7,7 +7,7 @@ import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 import { fileURLToPath } from 'node:url'
 import { claudeSlashCommands, codexSlashCommands, type SlashCommand } from './slash-commands.js'
-import { runtimeRoot, mainCheckout } from './layout.js'
+import { runtimeRoot, mainCheckout, readConfig } from './layout.js'
 import { tsxBin } from './tsx-bin.js'
 
 // @@@ harness-adapter - the ONE seam between SpexCode and the coding-agent harness (Claude Code, Codex, …).
@@ -609,7 +609,7 @@ export const claudeHarness: Harness = {
   events: CLAUDE_EVENTS,
   ownsRendezvous: true,                              // reclaude opens the rendezvous control socket (prompt delivery + liveness)
   paneTitleIsSelfSummary: true,                      // claude writes its live task summary into the OSC pane title → headline derives from it
-  launchCmd: () => process.env.SPEXCODE_CLAUDE_CMD || 'claude --dangerously-skip-permissions',
+  launchCmd: () => process.env.SPEXCODE_CLAUDE_CMD || readConfig(mainCheckout()).sessions?.claudeCmd || 'claude --dangerously-skip-permissions',
   sessionIdArg: (id) => `--session-id ${id}`,        // the caller chooses the id
   sessionEnvVar: 'CLAUDE_CODE_SESSION_ID',
   shimFile: (proj) => join(proj, '.claude', 'settings.json'),
@@ -628,7 +628,7 @@ export const codexHarness: Harness = {
   events: CODEX_EVENTS,
   ownsRendezvous: false,                             // no reclaude daemon — liveness + prompts through the project app-server socket
   paneTitleIsSelfSummary: false,                     // codex's pane title is a spinner + the cwd folder name, NOT a task summary → headline uses the prompt
-  launchCmd: (id, runtimeDir) => codexLaunchCommand(id, undefined, undefined, runtimeDir ?? runtimeRoot()),   // ONE app-server per PROJECT
+  launchCmd: (id, runtimeDir) => codexLaunchCommand(id, process.env.SPEXCODE_CODEX_CMD || readConfig(mainCheckout()).sessions?.codexCmd, undefined, runtimeDir ?? runtimeRoot()),   // env→config→default; ONE app-server per PROJECT
   sessionIdArg: () => '',                            // codex assigns its own id (the backend owns it via thread/start)
   sessionEnvVar: 'CODEX_THREAD_ID',
   // Codex discovers a LINKED worktree's PROJECT hooks from the ROOT CHECKOUT's `.codex`, NOT the worktree's

package/spec-cli/src/init.ts

@@ -45,6 +45,19 @@ function resolveHooksDir(dir: string): string | null {
 
 export async function specInit(targetArg: string | undefined): Promise<void> {
   const targetDir = resolve(targetArg ?? process.cwd())
+
+  // SpexCode is git-backed: git IS the version database and the hooks live in `.git`. A non-git target
+  // would leave a HALF-STATE — specs on disk but no version history, no hooks, no harness shims, no
+  // sessions. So fail LOUD before writing anything, rather than seeding debris and warning past it. We do
+  // NOT `git init` for them: creating a repo is a side effect beyond init's remit (a subdir, a dir not
+  // meant as a repo root), and `git init` is one deliberate command.
+  try {
+    execFileSync('git', ['-C', targetDir, 'rev-parse', '--is-inside-work-tree'], { stdio: ['ignore', 'ignore', 'ignore'] })
+  } catch {
+    console.error(`spex init: ${targetDir} is not a git repository. SpexCode is git-backed (git is the version database; the hooks live in .git). Run \`git init\` there first, then \`spex init\`.`)
+    process.exit(1)
+  }
+
   if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true })
   console.log(`spex init → ${targetDir}`)
 

package/spec-cli/src/layout.ts

@@ -16,6 +16,8 @@ type Config = {
   }
   sessions?: {
     maxActive?: number             // concurrency cap: max agents AUTONOMOUSLY PROGRESSING at once (default 6; see sessions.ts maxActive)
+    claudeCmd?: string             // worker launcher for Claude (default 'claude --dangerously-skip-permissions'); env SPEXCODE_CLAUDE_CMD overrides. A host-specific ABS path belongs in the gitignored spexcode.local.json, not here.
+    codexCmd?: string              // worker launcher for Codex (default 'codex --yolo'); env SPEXCODE_CODEX_CMD overrides. Same host-path rule.
   }
   serve?: {
     // public-exposure config for `spex serve --public` (resolved gateway-side; see [[public-mode]] / gateway.ts).
@@ -39,11 +41,24 @@ export type Worktree = {
 }
 export type Layout = { main: string; convention: Convention; worktrees: Worktree[] }
 
-export function readConfig(root: string): Config {
-  const p = join(root, 'spexcode.json')
+function readJsonOr(p: string): any {
   if (!existsSync(p)) return {}
   try { return JSON.parse(readFileSync(p, 'utf8')) } catch { return {} }
 }
+// committed `spexcode.json` with an OPTIONAL machine-local `spexcode.local.json` layered on top (gitignored).
+// The local layer is the durable home for HOST-SPECIFIC values that must never be committed — e.g. an
+// absolute worker-launcher path (the host-path leak the repo otherwise warns against). Precedence per field:
+// local over committed; an env var (e.g. SPEXCODE_CLAUDE_CMD) still overrides both at its read site.
+export function readConfig(root: string): Config {
+  const committed = readJsonOr(join(root, 'spexcode.json'))
+  const local = readJsonOr(join(root, 'spexcode.local.json'))
+  const out: any = { ...committed }
+  for (const k of Object.keys(local)) {
+    const b = committed[k], o = local[k]
+    out[k] = (b && o && typeof b === 'object' && typeof o === 'object' && !Array.isArray(o)) ? { ...b, ...o } : o
+  }
+  return out
+}
 
 // the shared git common dir (env-stripped git() so a hook's exported GIT_DIR can't misdirect it). Memoized:
 // it's a process constant, but mainBranch()/mainRoot() resolve it per call (~60 git rev-parse forks per board build without the cache).

package/spec-cli/src/materialize.ts

@@ -77,7 +77,11 @@ export function materialize(proj = process.cwd()): string {
   // only ignore paths that live INSIDE proj. The codex hooks shim now materializes at the MAIN checkout (codex
   // reads a linked worktree's hooks from the root checkout — see harness.ts); from a linked worktree that path
   // escapes proj (`../…`) and is gitignored by the main checkout's OWN materialize, not the worktree's.
-  const ignorable = shimPaths.filter((p) => !p.startsWith('..'))
+  // spexcode.local.json — the machine-local config overlay (host-specific values, e.g. an absolute worker
+  // launcher path; see portable-layout) — joins the SAME block on the same rationale: machine-specific, must
+  // never be committed. Without it an adopter who follows our own guidance to put a host path there would
+  // `git add -A` and leak it — the exact thing the overlay exists to prevent.
+  const ignorable = [...shimPaths.filter((p) => !p.startsWith('..')), 'spexcode.local.json']
   if (ignorable.length) writeManagedBlock(join(proj, '.gitignore'), ignorable.sort().join('\n'), ['# ', ''])
   // (5) stamp the content-hash marker LAST (so a crash mid-render leaves it stale → re-renders next gate).
   const h = contentHash(proj)