@gobing-ai/spur 0.1.8

package/spur-cli/config/rules/strict/http-boundaries.yaml

@@ -0,0 +1,70 @@
+# [STRICT — opt-in] HTTP-client boundaries. Absorbed from
+# ts-libs/.spur/rules/typescript/external-api-boundaries.yaml. NOT in
+# recommended-pre-check: Spur has no central api-client seam yet, and the
+# server's Hono/Workers entrypoint legitimately exposes a `fetch` handler.
+# Opt in via: spur rule run --preset strict  (or --rule <id>).
+include:
+  - "apps/**/src/**/*.ts"
+  - "packages/**/src/**/*.ts"
+exclude:
+  - "**/tests/**"
+  - "**/*.test.ts"
+  - "**/node_modules/**"
+  - "**/dist/**"
+
+rules:
+  - id: no-direct-fetch
+    description: "Prefer a centralized HTTP client over ad-hoc fetch(...). The server's Hono/Workers fetch entrypoint is exempt."
+    severity: warning
+    evaluator:
+      type: rg
+      config:
+        pattern: "(^|[^.[:alnum:]_])fetch\\("
+    exclude:
+      # Hono/Cloudflare Workers entrypoint — `fetch` is the platform contract.
+      - "apps/server/src/worker.ts"
+      - "apps/server/src/app.ts"
+
+  - id: no-globalthis-fetch
+    description: "Avoid globalThis.fetch(...); route HTTP through a client seam when one exists."
+    severity: warning
+    evaluator:
+      type: rg
+      config:
+        pattern: "globalThis\\.fetch\\("
+
+  - id: no-xml-http-request
+    description: "Do not use XMLHttpRequest in a Bun/Node codebase."
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        pattern: "new\\s+XMLHttpRequest\\("
+    # Correctness rule (not a seam rule): XHR is never valid under Bun, so it
+    # applies to scripts/ tooling too — override the file-level apps+packages scope.
+    include:
+      - "apps/**/src/**/*.ts"
+      - "packages/**/src/**/*.ts"
+      - "scripts/**/*.ts"
+
+  - id: no-third-party-http-clients
+    description: "Use the platform fetch / a project client instead of ad-hoc HTTP client libraries (axios/got/ky/ofetch/undici)."
+    severity: error
+    evaluator:
+      type: forbidden-import
+      config:
+        forbidden:
+          - specifier: "axios"
+          - specifier: "got"
+          - specifier: "ky"
+          - specifier: "ofetch"
+          - specifier: "undici"
+        scope:
+          include:
+            - "apps/**/*.ts"
+            - "packages/**/*.ts"
+            - "scripts/**/*.ts"
+          exclude:
+            - "**/tests/**"
+            - "**/*.test.ts"
+            - "**/dist/**"

package/spur-cli/config/rules/strict/rule-files-structural.yaml

@@ -0,0 +1,55 @@
+# [STRICT — opt-in] Meta-validation for local .spur/rules YAML. Absorbed from
+# ts-libs/.spur/rules/meta/rule-files-structural.yaml. The engine already
+# validates rule files on load, so this is a redundant pre-commit self-check;
+# it also requires `yq` + `rg` on PATH. Opt-in only.
+rules:
+  - id: rule-yaml-files-valid-structure
+    description: "Local .spur/rules YAML files must parse and expose either rule entries or a preset (name + extends)."
+    severity: error
+    evaluator:
+      type: exit-code
+      config:
+        command: sh
+        args:
+          - -c
+          - |
+            command -v yq >/dev/null 2>&1 || { echo "SKIP: yq not on PATH"; exit 0; }
+            command -v rg >/dev/null 2>&1 || { echo "SKIP: rg not on PATH"; exit 0; }
+            errors=0
+            for f in $(rg --files .spur/rules -g '*.yaml'); do
+              if ! yq -e '.' "$f" >/dev/null 2>&1; then
+                echo "INVALID: $f is not valid YAML"
+                errors=$((errors + 1))
+                continue
+              fi
+
+              if yq -e '.rules != null' "$f" >/dev/null 2>&1; then
+                if ! yq -e '.rules | type == "!!seq"' "$f" >/dev/null 2>&1; then
+                  echo "INVALID: $f: .rules must be an array"
+                  errors=$((errors + 1))
+                  continue
+                fi
+                count="$(yq '.rules | length' "$f")"
+                i=0
+                while [ "$i" -lt "$count" ]; do
+                  rid="$(yq ".rules[$i].id // \"\"" "$f")"
+                  rdesc="$(yq ".rules[$i].description // \"\"" "$f")"
+                  rtype="$(yq ".rules[$i].evaluator.type // \"\"" "$f")"
+                  [ -n "$rid" ] && [ "$rid" != "null" ] || { echo "INVALID: $f: rules[$i] missing id"; errors=$((errors + 1)); }
+                  [ -n "$rdesc" ] && [ "$rdesc" != "null" ] || { echo "INVALID: $f: rules[$i] missing description"; errors=$((errors + 1)); }
+                  [ -n "$rtype" ] && [ "$rtype" != "null" ] || { echo "INVALID: $f: rules[$i] missing evaluator.type"; errors=$((errors + 1)); }
+                  i=$((i + 1))
+                done
+              elif yq -e '.name != null' "$f" >/dev/null 2>&1; then
+                if ! yq -e '.extends | type == "!!seq"' "$f" >/dev/null 2>&1; then
+                  echo "INVALID: $f: presets must define an extends array"
+                  errors=$((errors + 1))
+                fi
+              else
+                echo "INVALID: $f: expected .rules or .name"
+                errors=$((errors + 1))
+              fi
+            done
+            [ "$errors" -eq 0 ] || exit 1
+    include:
+      - ".spur/rules/**/*.yaml"

package/spur-cli/config/rules/strict/runtime-boundaries.yaml

@@ -0,0 +1,64 @@
+# [STRICT — opt-in] Runtime boundaries. Absorbed from
+# ts-libs/.spur/rules/typescript/runtime-boundaries.yaml. NOT in
+# recommended-pre-check: Spur consumes ts-runtime's ProcessExecutor/FileSystem
+# seams but also does light direct fs/spawn at app edges, so these run as
+# opt-in hygiene with explicit allowlists for the sanctioned sites.
+# `no-direct-process-env` is intentionally omitted — config-from-env is Spur's
+# design (packages/config, apps/cli/context).
+include:
+  - "apps/**/src/**/*.ts"
+  - "packages/**/src/**/*.ts"
+exclude:
+  - "**/tests/**"
+  - "**/*.test.ts"
+  - "**/node_modules/**"
+  - "**/dist/**"
+
+rules:
+  - id: no-direct-process-spawn
+    description: "Agent/process execution must go through ts-ai-runner / ts-runtime's ProcessExecutor. The only sanctioned direct spawn is `spur agent edit` opening $EDITOR."
+    severity: warning
+    evaluator:
+      type: forbidden-import
+      config:
+        forbidden:
+          - specifier: "node:child_process"
+          - specifier: "child_process"
+          - pattern: "Bun\\.(spawn|spawnSync)\\s*\\("
+            matchMode: usage
+          - specifier: "execa"
+          - specifier: "zx"
+        scope:
+          include:
+            - "apps/**/src/**/*.ts"
+            - "packages/**/src/**/*.ts"
+          exclude:
+            - "**/tests/**"
+            - "**/*.test.ts"
+            - "**/dist/**"
+            # `spur agent edit` opens the operator's $EDITOR interactively.
+            - "apps/cli/src/commands/agent.ts"
+
+  - id: no-direct-fs-io
+    description: "Prefer ts-runtime's FileSystem seam for fs IO. Light direct fs at app edges (service stat/access, migration loading) is allowlisted."
+    severity: warning
+    evaluator:
+      type: forbidden-import
+      config:
+        forbidden:
+          - pattern: "from\\s+['\"]node:fs(?:/promises)?['\"]|require\\(['\"]node:fs"
+            matchMode: usage
+          - pattern: "\\bBun\\.(?:write)\\("
+            matchMode: usage
+        scope:
+          include:
+            - "apps/**/src/**/*.ts"
+            - "packages/**/src/**/*.ts"
+          exclude:
+            - "**/tests/**"
+            - "**/*.test.ts"
+            - "**/dist/**"
+            # Sanctioned direct-fs sites (no local FileSystem seam re-implemented):
+            - "packages/app/src/services/workflow-service.ts"
+            - "packages/app/src/services/agent-service.ts"
+            - "packages/domain/src/migrations.ts"

package/spur-cli/config/rules/strict-check.yaml

@@ -0,0 +1,15 @@
+# Strict-check preset — opt-in hygiene rules absorbed from ts-libs but kept OUT
+# of the default recommended-pre-check gate (they need project-specific tuning
+# or are redundant with engine-level validation). Run explicitly:
+#   spur rule run --preset strict-check
+# or cherry-pick a single rule:
+#   spur rule run --rule no-third-party-http-clients
+#
+# `extends: [strict]` references the strict/ category directory (the preset file
+# is named differently to avoid a name↔category collision).
+name: strict-check
+description: >
+  Opt-in boundary hygiene: HTTP-client centralization, runtime fs/spawn seams,
+  and local rule-file structural validation. Not part of recommended-pre-check.
+extends:
+  - strict

package/spur-cli/config/rules/structure/protected-files.yaml

@@ -0,0 +1,62 @@
+# Protected-file rules — secret detection and git/repo safety. Absorbed from
+# ts-libs/.spur/rules/structure/protected-files.yaml, re-scoped for apps/** +
+# packages/** + scripts/** (release/dev tooling is a prime secret-leak site).
+# Mirrors the AGENTS.md safety boundaries (no secrets, no .env, no unreviewed
+# workflows, no destructive git).
+rules:
+  - id: no-hardcoded-secrets
+    description: "Hardcoded secrets detected; read secrets from environment/config boundaries instead. Spur never stores agent API keys (AGENTS.md)."
+    severity: error
+    evaluator:
+      type: secrets-scanner
+      config:
+        categories: [api-key, token, private-key, password, connection-string]
+        # The secrets-scanner uses the in-process LOOSE matcher (substring/suffix
+        # fragments), not ripgrep globs. Deep globs like `apps/**/*.ts` collapse to
+        # `apps/.ts` and match NOTHING — so scope must be path FRAGMENTS:
+        # `apps/`, `packages/`, `scripts/` cover all TS source via substring match.
+        scope:
+          include:
+            - "apps/"
+            - "packages/"
+            - "scripts/"
+          exclude:
+            - "/tests/"
+            - ".test.ts"
+            - "/node_modules/"
+            - "/dist/"
+
+  - id: no-unsafe-git-commands
+    description: "Unsafe git commands (force-push, hard reset) can overwrite history or cause data loss (AGENTS.md CRITICAL safety)."
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        pattern: "git\\s+.*(push\\s+.*--force|push\\s+.*--force-with-lease\\b)|git\\s+.*reset\\s+--hard\\b"
+    include:
+      - "**/*.sh"
+      - "**/*.bash"
+      - "scripts/**/*.ts"
+      - "package.json"
+      - ".github/**/*.yml"
+      - ".github/**/*.yaml"
+
+  - id: no-env-files
+    description: ".env files must not be committed; use checked-in examples only (AGENTS.md: never commit .env*)."
+    severity: error
+    evaluator:
+      type: path
+      config:
+        must: absent
+    include:
+      - "**/.env"
+      - "**/.env.*"
+    exclude:
+      - "**/.env.example"
+      - "**/node_modules/**"
+
+# NOTE: the ts-libs `no-github-workflows` rule (asserting .github/workflows must be
+# ABSENT) was intentionally NOT absorbed — ts-libs is a library repo with no CI,
+# but Spur is an application repo that legitimately ships ci.yml + publish.yml.
+# "Never edit workflows without approval" (AGENTS.md) is a process rule for agents,
+# not a file-absence assertion.

package/spur-cli/config/rules/structure/test-focus-skip.yaml

@@ -0,0 +1,27 @@
+# No focused or skipped tests committed to the suite.
+# Part of the recommended-pre-check preset — caught BEFORE the suite runs so a
+# narrowed or disabled test never lands on a branch and silently shrinks
+# coverage.
+#
+# Scope: test files only (*.test.ts / *.test.tsx). The bare `.only(` / `.skip(`
+# arms are safe here because the bun:test focus/skip API is the only thing in a
+# test file that uses them; restricting scope avoids false positives on unrelated
+# `.skip()` calls elsewhere. Pattern is ripgrep dialect (no lookbehind/backrefs).
+include:
+  - "apps/**/tests/**/*.test.ts"
+  - "apps/**/tests/**/*.test.tsx"
+  - "packages/**/tests/**/*.test.ts"
+  - "packages/**/tests/**/*.test.tsx"
+exclude:
+  - "**/node_modules/**"
+rules:
+  - id: no-focused-or-skipped-tests
+    description: >
+      Do not commit focused (.only) or skipped (.skip) tests. They narrow or
+      disable the suite, masking failures and coverage gaps. Remove the modifier
+      before committing; quarantine flaky tests with a tracked issue instead.
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        pattern: "\\b(describe|it|test|bench)\\.(only|skip)\\(|\\b(fdescribe|fit|xdescribe|xit)\\("

package/spur-cli/config/rules/structure/test-location.yaml

@@ -0,0 +1,44 @@
+# Local override of the global structure/test-location.yaml — same relative path,
+# so it shadows the global copy (local wins in the layered merge) and the
+# `require-corresponding-test` rule is defined exactly once. Keeps `no-tests-dir`
+# from the global file and adds project-specific excludes (declaration-only files,
+# schema/migration/db modules) to `require-corresponding-test`.
+rules:
+  - id: no-tests-dir
+    description: "Tests must live in tests/ directories at the same level as src/, not in __tests__."
+    severity: error
+    evaluator:
+      type: test-location
+      config:
+        expected: "**/*.test.*"
+        forbid:
+          - "**/__tests__/**"
+          - "**/src/**/*.test.ts"
+          - "**/src/**/*.test.tsx"
+        requireCorrespondingTest: false
+    include:
+      - "packages/**/tests/**/*.test.ts"
+      - "apps/**/tests/**/*.test.ts"
+      - "packages/**/tests/**/*.test.tsx"
+      - "apps/**/tests/**/*.test.tsx"
+
+  - id: require-corresponding-test
+    description: "Every source file must have a corresponding test in tests/, excluding declaration-only files."
+    severity: warning
+    evaluator:
+      type: test-location
+      config:
+        expected: "**/*.test.*"
+        requireCorrespondingTest: true
+    include:
+      - "packages/**/src/**/*.ts"
+      - "apps/**/src/**/*.ts"
+    exclude:
+      - "**/index.ts"
+      - "**/*.d.ts"
+      - "**/types.ts"
+      - "**/schema/**"
+      - "**/migrations.ts"
+      - "**/db.ts"
+      - "**/node_modules/**"
+      - "**/tests/**"

package/spur-cli/config/rules/surface/check-cli-surface.yaml

@@ -0,0 +1,35 @@
+# CLI surface consistency — structural checks that every command file follows
+# the registerXxxCommand convention and that --json claims are backed by real
+# output serialization (toJson or JSON.stringify).
+#
+# Part of the recommended-pre-check preset. Run:
+#   spur rule run --preset recommended-pre-check
+
+include:
+  - "apps/cli/src/commands/*.ts"
+
+exclude:
+  - "apps/cli/src/commands/stubs.ts"
+
+rules:
+  - id: cli-register-pattern
+    description: >
+      Every CLI command file must export a registerXxxCommand(program, context)
+      function matching the standard Commander.js wiring pattern.
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        pattern: "export function register\\w+Command\\("
+        mode: require
+
+  - id: cli-json-output
+    description: >
+      Command files that register --json options must call toJson() or
+      JSON.stringify() to produce machine-readable output.
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        pattern: "toJson\\b|JSON\\.stringify\\b"
+        mode: require

package/spur-cli/config/rules/typescript/bun-tooling.yaml

@@ -0,0 +1,61 @@
+# Bun/tooling rules — Spur standardizes on Bun + bun:test (AGENTS.md "Stack").
+# Absorbed from ts-libs/.spur/rules/typescript/bun-only.yaml, re-scoped for the
+# apps/** + packages/** + scripts/** app-monorepo layout and the server's
+# Cloudflare Workers Vitest suite (the one sanctioned non-bun:test runner — `*.cf.ts`).
+include:
+  - "package.json"
+  - "apps/**/*.ts"
+  - "packages/**/*.ts"
+  - "scripts/**/*.ts"
+  - ".spur/**/*.yaml"
+exclude:
+  - "**/node_modules/**"
+  - "**/dist/**"
+
+rules:
+  - id: no-npm-pnpm-yarn-scripts
+    description: "Use bun scripts instead of npm, pnpm, or yarn commands (AGENTS.md: no npm/pnpm/yarn)."
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        pattern: "\\b(npm run|pnpm|yarn)\\b"
+    include:
+      - "package.json"
+      - "apps/*/package.json"
+      - "packages/*/package.json"
+      - "scripts/**/*.ts"
+      - "**/*.yml"
+      - "**/*.yaml"
+    exclude:
+      # Rule-definition YAML legitimately names these tools in patterns/descriptions.
+      - "config/rules/**"
+      - ".spur/rules/**"
+
+  - id: enforce-bun-test
+    description: "Unit/integration tests must use bun:test, not Jest or Mocha. The server's Cloudflare Workers suite (*.cf.ts) is the only sanctioned Vitest runner."
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        pattern: "from [''\"](jest|mocha|@jest)"
+    include:
+      - "apps/**/*.test.ts"
+      - "packages/**/*.test.ts"
+      - "scripts/**/*.test.ts"
+
+  - id: no-vitest-imports-or-apis
+    description: "Use bun:test APIs instead of vitest, except the server's Cloudflare Workers tests (*.cf.ts) which must run under the Workers pool via Vitest."
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        pattern: "from ['\"]vitest['\"]|vi\\.(fn|spyOn|mock|stub)\\b"
+    include:
+      - "apps/**/*.ts"
+      - "packages/**/*.ts"
+      - "scripts/**/*.ts"
+    exclude:
+      - "apps/server/tests/cf/**"
+      - "apps/server/vitest.cf.config.ts"
+      - "**/*.cf.ts"

package/spur-cli/config/rules/typescript/no-biome-suppressions.yaml

@@ -0,0 +1,29 @@
+# No Biome suppression comments in production source.
+# Absorbed from ts-libs/.spur/rules/typescript/no-biome-suppressions.yaml,
+# re-scoped to Spur's monorepo layout:
+#   - the `rg` evaluator forwards include/exclude to ripgrep as proper globs,
+#     so it handles deep ** globs correctly (unlike the legacy regex matcher,
+#     which forced a `src/` substring workaround). Scope is the real
+#     apps/**/src + packages/**/src production source plus scripts/** tooling.
+#   - test files excluded where noExplicitAny / useLiteralKeys suppressions
+#     are sometimes legitimate in test helpers
+#   - severity kept as error (encodes AGENTS.md gate rule: "No new biome-ignore
+#     added solely to silence the gate")
+include:
+  - "apps/**/src/**/*.ts"
+  - "packages/**/src/**/*.ts"
+  - "scripts/**/*.ts"
+exclude:
+  - "**/node_modules/**"
+  - "**/dist/**"
+  - "**/tests/**"
+rules:
+  - id: no-biome-suppressions
+    description: >
+      Do not use biome-ignore or biome-ignore-all comments to suppress lint
+      rules.  Fix the underlying issue instead.
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        pattern: "biome-ignore"

package/spur-cli/config/rules/typescript/no-debugger.yaml

@@ -0,0 +1,27 @@
+# No `debugger` statements in production source.
+# Part of the recommended-pre-check preset — a debugger left in shipped source
+# halts execution under an attached inspector and is never intended for commit.
+#
+# Scope: production source plus scripts tooling. Tests excluded (a debugger in a
+# local test run is a transient debugging aid, not shipped behavior) — though the
+# focus/skip rule already guards the more common test-hygiene mistake. Pattern is
+# ripgrep dialect: `\bdebugger\b` matches the statement, not substrings like
+# `debuggerPort`.
+include:
+  - "apps/**/src/**/*.ts"
+  - "packages/**/src/**/*.ts"
+  - "scripts/**/*.ts"
+exclude:
+  - "**/node_modules/**"
+  - "**/dist/**"
+  - "**/tests/**"
+rules:
+  - id: no-debugger-statement
+    description: >
+      Do not commit `debugger` statements in production source. They pause
+      execution under an attached inspector and have no place in shipped code.
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        pattern: "\\bdebugger\\b\\s*;?"

package/spur-cli/config/rules/typescript/output-boundaries.yaml

@@ -0,0 +1,28 @@
+# Output boundary rules — terminal writes go through the output seam
+# (apps/cli/src/output.ts → ts-utils echo/echoError), never raw console/stdout.
+# Absorbed from ts-libs/.spur/rules/typescript/no-raw-output.yaml, re-scoped to
+# the app-monorepo layout. Spur's only sanctioned sink is the ts-utils helper,
+# so no local exclusions are needed.
+include:
+  - "apps/**/src/**/*.ts"
+  - "packages/**/src/**/*.ts"
+exclude:
+  - "**/node_modules/**"
+  - "**/dist/**"
+
+rules:
+  - id: no-console-output
+    description: "Production source must use the output seam (apps/cli/src/output.ts / ts-utils echo) instead of direct console output."
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        pattern: "console\\.(log|error|warn|info|debug|dir|time|trace)"
+
+  - id: no-raw-stdout-stderr
+    description: "Use the output seam (ts-utils echo/echoError) instead of process.stdout/stderr.write directly."
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        pattern: "process\\.(stdout|stderr)\\.write"

package/spur-cli/config/workflows/basic.yaml

@@ -0,0 +1,58 @@
+# Canonical basic workflow: implement -> check -> fix until the check passes or the
+# iteration bound is exhausted. Authored for the @gobing-ai/ts-dual-workflow-engine
+# state-machine schema (initialState / states[].id / onEnter / top-level transitions).
+# See Architecture Section 5 and Design Section 3.3.
+name: basic
+kind: state-machine
+description: The canonical implement-check-fix-until-pass loop
+iterationBound: 2
+initialState: implement
+terminalStates:
+  - done
+  - failed
+states:
+  - id: implement
+    description: Implement the requested task
+    onEnter:
+      - kind: note
+        options:
+          message: 'Implementing task: ${task}'
+
+  - id: check
+    description: Verify the implementation passes all checks
+    onEnter:
+      - kind: shell
+        options:
+          command: bun run check
+
+  - id: fix
+    description: Address failures from the check pass
+    onEnter:
+      - kind: note
+        options:
+          message: 'Please fix the issues found'
+
+  - id: done
+    description: Terminal — workflow completed successfully
+  - id: failed
+    description: Terminal — workflow failed
+
+transitions:
+  - from: implement
+    to: check
+    description: Hand the implemented task to the check pass
+
+  # Check passed -> done; otherwise loop back to fix. Declaration order matters:
+  # the action-ok guard is tried first, so a passing check short-circuits to done.
+  - from: check
+    to: done
+    description: Check passed — finish successfully
+    guard:
+      kind: action-ok
+  - from: check
+    to: fix
+    description: Check failed — route to a fix attempt
+
+  - from: fix
+    to: check
+    description: Re-run the check after fixing