@codedology/code-forge 0.1.0

package/examples/node-lib/src/math.mjs

@@ -0,0 +1,21 @@
+/** Small number helpers. */
+
+/** @param {number} a @param {number} b @returns {number} */
+export function add(a, b) {
+  return a + b;
+}
+
+/** @param {number} a @param {number} b @returns {number} */
+export function sub(a, b) {
+  return a - b;
+}
+
+/**
+ * @param {number[]} values
+ * @returns {number} the arithmetic mean
+ * @throws {RangeError} on an empty list
+ */
+export function mean(values) {
+  if (values.length === 0) throw new RangeError('mean of an empty list');
+  return values.reduce(add, 0) / values.length;
+}

package/examples/node-lib/src/strings.mjs

@@ -0,0 +1,34 @@
+/** Small string helpers. */
+
+import { readFileSync } from 'node:fs';
+
+/**
+ * @param {string} text @param {number} width @param {{side?: 'left' | 'right', fill?: string}} [opts]
+ * @returns {string} `text` padded to `width` characters
+ */
+export function pad(text, width, { side = 'left', fill = ' ' } = {}) {
+  return side === 'left' ? text.padStart(width, fill) : text.padEnd(width, fill);
+}
+
+/** @param {string} text @returns {string} */
+export function capitalize(text) {
+  return text.length === 0 ? text : text[0].toUpperCase() + text.slice(1);
+}
+
+/**
+ * `GREETING` from a dotenv-style file (default `.env` in the current directory), or `hi`.
+ * @param {string} name @param {string} [envFile]
+ * @returns {string}
+ */
+export function greet(name, envFile = '.env') {
+  let word = 'hi';
+  try {
+    const line = readFileSync(envFile, 'utf8')
+      .split('\n')
+      .find((l) => l.startsWith('GREETING='));
+    if (line) word = line.slice('GREETING='.length).trim();
+  } catch {
+    // no env file: the default greeting
+  }
+  return `${capitalize(word)}, ${name}!`;
+}

package/examples/node-lib/test/list.test.mjs

@@ -0,0 +1,12 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { chunk, unique } from '../src/list.mjs';
+
+test('chunk splits into slices of at most size items', () => {
+  assert.deepEqual(chunk([1, 2, 3, 4, 5], 2), [[1, 2], [3, 4], [5]]);
+  assert.throws(() => chunk([1], 0), RangeError);
+});
+
+test('unique keeps the first occurrence, in order', () => {
+  assert.deepEqual(unique([3, 1, 3, 2, 1]), [3, 1, 2]);
+});

package/examples/node-lib/test/math.test.mjs

@@ -0,0 +1,13 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { add, mean, sub } from '../src/math.mjs';
+
+test('add and sub', () => {
+  assert.equal(add(2, 3), 5);
+  assert.equal(sub(2, 3), -1);
+});
+
+test('mean of three values, and of none', () => {
+  assert.equal(mean([1, 2, 6]), 3);
+  assert.throws(() => mean([]), RangeError);
+});

package/examples/node-lib/test/package.test.mjs

@@ -0,0 +1,18 @@
+// The release files a measurement export must restore: `.gitattributes` marks both export-ignore.
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { test } from 'node:test';
+
+const root = new URL('../', import.meta.url);
+const read = (/** @type {string} */ rel) => readFileSync(new URL(rel, root), 'utf8');
+
+test('CHANGELOG.md has a section for the package version', () => {
+  const { version } = JSON.parse(read('package.json'));
+  assert.equal(read('CHANGELOG.md').includes(`\n## ${version}\n`), true);
+});
+
+test('the CI workflow runs npm test on Node 22', () => {
+  const workflow = read('.github/workflows/test.yml');
+  assert.equal(workflow.includes('node-version: 22'), true);
+  assert.equal(workflow.includes('- run: npm test'), true);
+});

package/examples/node-lib/test/strings.test.mjs

@@ -0,0 +1,28 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { test } from 'node:test';
+import { capitalize, greet, pad } from '../src/strings.mjs';
+
+test('pad on either side', () => {
+  assert.equal(pad('7', 3), '  7');
+  assert.equal(pad('7', 3, { side: 'right', fill: '.' }), '7..');
+});
+
+test('capitalize keeps the empty string', () => {
+  assert.equal(capitalize('ada'), 'Ada');
+  assert.equal(capitalize(''), '');
+});
+
+test('greet reads GREETING from the env file, else says hi', () => {
+  const dir = mkdtempSync(path.join(os.tmpdir(), 'node-lib-'));
+  try {
+    const file = path.join(dir, '.env');
+    writeFileSync(file, 'GREETING=hello\n');
+    assert.equal(greet('Ada', file), 'Hello, Ada!');
+    assert.equal(greet('Ada', path.join(dir, 'missing.env')), 'Hi, Ada!');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@codedology/code-forge",
+  "version": "0.1.0",
+  "description": "Plan/harden/code/review orchestration CLI and Agent Skill for cross-model, parallel, evidence-gated feature delivery.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ricardov03/code-forge.git"
+  },
+  "homepage": "https://github.com/ricardov03/code-forge#readme",
+  "bugs": {
+    "url": "https://github.com/ricardov03/code-forge/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "code-forge": "bin/code-forge.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "schema",
+    "skill",
+    "docs/reference",
+    "examples",
+    "scripts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "CODE_FORGE_NO_LEAK=snapshot node --import ./test/helpers/isolate.mjs --test test/no-leak.test.mjs && node --import ./test/helpers/isolate.mjs --experimental-test-module-mocks --test 'test/**/*.test.mjs' && CODE_FORGE_NO_LEAK=final node --import ./test/helpers/isolate.mjs --test test/no-leak.test.mjs",
+    "typecheck": "tsc --checkJs --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "1.8.1",
+    "ajv": "8.20.0",
+    "yaml": "2.9.1"
+  },
+  "optionalDependencies": {
+    "@napi-rs/keyring": "2.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.4",
+    "typescript": "7.0.2"
+  }
+}

package/schema/code-forge.schema.json

@@ -0,0 +1,331 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://code-forge.dev/schema/code-forge.schema.json",
+  "title": "code-forge project configuration (.code-forge.yml)",
+  "description": "Plan v1.2 §1.3 — every key any section of the plan reads must appear here. additionalProperties: false everywhere a key set is fixed; a typed additionalProperties schema (never bare true) marks the handful of genuinely open-ended maps (thresholds.<question>, system1.criteria_extra, known_extra, keys, review.second_levels — the last restricted to L0..L3 keys only via propertyNames). v1.3 (B1.1) amendment: review.max_rounds_per_file/recheck_scope/late_findings (§4.11), budget.block_cases (§10.7), caps.coders re-defaulted to 2 (R10), tmp.root (§9.6/§1.2, V12).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "provider", "levels"],
+  "$comment": "version/provider/levels are REQUIRED with NO schema-level default (a config omitting them is refused here) — `migrate.mjs` fills a MISSING `version` to CURRENT_VERSION before this schema ever runs (so an on-disk file may omit `version`), but `provider` has no such auto-fill anywhere and must be present in the loaded document.",
+  "properties": {
+    "version": { "type": "integer", "const": 1 },
+    "project": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string" },
+        "slug": { "type": "string" },
+        "plans_dir": { "type": "string" },
+        "languages": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "chat": { "type": "string" },
+            "ui": { "type": "string" },
+            "pr": { "type": "string" }
+          }
+        }
+      }
+    },
+    "provider": { "$ref": "#/$defs/provider" },
+    "levels": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["L0", "L1", "L2", "L3"],
+      "properties": {
+        "L0": { "$ref": "#/$defs/level" },
+        "L1": { "$ref": "#/$defs/level" },
+        "L2": { "$ref": "#/$defs/level" },
+        "L3": { "$ref": "#/$defs/level" }
+      }
+    },
+    "orchestrator": { "$ref": "#/$defs/levelName" },
+    "system1": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "provider": { "$ref": "#/$defs/provider" },
+        "model": { "type": "string" },
+        "key": { "type": "string" },
+        "fallback": { "type": "string", "enum": ["rules", "s2", "stop"], "default": "rules" },
+        "criteria_extra": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "instructions": { "type": "string" },
+              "criteria": { "type": "object", "additionalProperties": { "type": "string" } }
+            }
+          }
+        },
+        "disable": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "thresholds": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/thresholdBand" },
+      "properties": {
+        "default": { "$ref": "#/$defs/thresholdBand" },
+        "findings": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "fix": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.9 },
+            "nit": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.4 },
+            "resolved": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.9 }
+          }
+        }
+      }
+    },
+    "escalation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "retries_per_level": { "type": "integer", "minimum": 0, "default": 2 },
+        "review_rounds_per_level": { "type": "integer", "minimum": 0, "default": 2 },
+        "stop_at": { "type": "string", "const": "L3", "default": "L3" },
+        "l3_mode": { "type": "string", "enum": ["patch", "code"], "default": "patch" }
+      }
+    },
+    "review": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "multimodel": { "type": "boolean", "default": false },
+        "second_provider": { "anyOf": [{ "$ref": "#/$defs/provider" }, { "type": "null" }], "default": null },
+        "second_levels": {
+          "anyOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "propertyNames": { "$ref": "#/$defs/levelName" },
+              "additionalProperties": { "$ref": "#/$defs/level" }
+            }
+          ],
+          "default": null
+        },
+        "closed_book": { "type": "boolean", "const": true, "default": true },
+        "judge_sees_diff": { "type": "boolean", "default": false },
+        "budgets": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "quick_in": { "type": "integer", "minimum": 1, "default": 6000 },
+            "full_in": { "type": "integer", "minimum": 1, "default": 12000 },
+            "judge_in": { "type": "integer", "minimum": 1, "default": 8000 },
+            "out": { "type": "integer", "minimum": 1, "default": 1200 }
+          }
+        },
+        "context": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "whole_file_max_lines": { "type": "integer", "minimum": 0, "default": 400 },
+            "hunk_context_lines": { "type": "integer", "minimum": 0, "default": 40 },
+            "min_context_lines": { "type": "integer", "minimum": 0, "default": 10 }
+          }
+        },
+        "block_budget_tokens": { "type": "integer", "minimum": 1, "default": 150000 },
+        "block_budget_usd": {
+          "anyOf": [{ "type": "number", "exclusiveMinimum": 0 }, { "type": "null" }],
+          "default": null
+        },
+        "min_tokens_out": { "type": "integer", "minimum": 1, "default": 120 },
+        "batch_small_files": { "type": "boolean", "default": true },
+        "session_timeout_s": { "type": "integer", "minimum": 1, "default": 600 },
+        "max_rounds_per_file": { "type": "integer", "minimum": 2, "maximum": 6, "default": 4 },
+        "recheck_scope": { "type": "string", "enum": ["fix_hunks", "file"], "default": "fix_hunks" },
+        "late_findings": { "type": "string", "enum": ["sweep", "block"], "default": "sweep" }
+      }
+    },
+    "engine": { "type": "string", "enum": ["auto", "solo", "harness", "subprocess"], "default": "auto" },
+    "harnesses": { "type": "array", "items": { "type": "string" } },
+    "harness": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "claude": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": { "worktree": { "type": "boolean", "default": false } }
+        },
+        "solo": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": { "interactive_harden": { "type": "boolean", "default": false } }
+        }
+      }
+    },
+    "caps": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": { "coders": { "type": "integer", "minimum": 1, "default": 2 } }
+    },
+    "gates": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "test": { "$ref": "#/$defs/argvOrNull" },
+        "lint": { "$ref": "#/$defs/argvOrNull" },
+        "types": { "$ref": "#/$defs/argvOrNull" },
+        "format": { "$ref": "#/$defs/argvOrNull" },
+        "extra": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "secret_scan": { "type": "boolean", "default": true },
+            "safe_edit": { "type": "boolean", "default": true },
+            "invariants": { "type": "string" }
+          }
+        },
+        "full_suite_threshold_files": { "type": "integer", "minimum": 1, "default": 10 }
+      }
+    },
+    "proof": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tiers": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "high": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "paths": { "type": "array", "items": { "type": "string" } }
+              }
+            },
+            "light": { "type": "object", "additionalProperties": false, "properties": {} }
+          }
+        },
+        "extra": { "type": "array", "items": { "type": "string" } },
+        "isolation": { "type": "string", "enum": ["export", "lock"], "default": "export" },
+        "export": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "link_dirs": {
+              "type": "array",
+              "items": { "type": "string" },
+              "default": ["vendor", "node_modules"]
+            },
+            "copy_untracked": {
+              "type": "array",
+              "items": { "type": "string" },
+              "default": [".env", ".env.testing"]
+            }
+          }
+        }
+      }
+    },
+    "budget": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "block_lines": { "type": "integer", "minimum": 1, "default": 600 },
+        "block_tokens_soft": { "type": "integer", "minimum": 1 },
+        "block_tokens_hard": { "type": "integer", "minimum": 1 },
+        "run_usd_soft": { "type": "number", "minimum": 0 },
+        "block_cases": { "type": "integer", "minimum": 10, "default": 80 }
+      }
+    },
+    "autonomy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "coder_may_open_draft_pr": { "type": "boolean", "default": true },
+        "coder_may_push": { "type": "boolean", "default": true }
+      }
+    },
+    "commit": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "trailers": { "type": "string", "enum": ["none", "harness"], "default": "none" }
+      }
+    },
+    "wip": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": { "ready_prs": { "type": "integer", "minimum": 1, "default": 1 } }
+    },
+    "production": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "markers": { "type": "array", "items": { "type": "string" } },
+        "names": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "known_extra": {
+      "type": "object",
+      "additionalProperties": { "type": "array", "items": { "type": "string" } }
+    },
+    "calibration": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "shadow_rate": { "type": "number", "minimum": 0, "maximum": 0.5, "default": 0 }
+      }
+    },
+    "keys": {
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    },
+    "tmp": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "root": {
+          "anyOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }],
+          "default": null
+        }
+      }
+    },
+    "telemetry": { "type": "string", "const": "off", "default": "off" }
+  },
+  "$defs": {
+    "provider": { "type": "string", "enum": ["anthropic", "openai", "xai"] },
+    "levelName": { "type": "string", "enum": ["L0", "L1", "L2", "L3"] },
+    "level": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["model"],
+      "properties": {
+        "model": { "type": "string", "minLength": 1 },
+        "effort": { "type": "string" },
+        "provider": { "$ref": "#/$defs/provider" },
+        "fallback": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["provider", "model"],
+            "properties": {
+              "provider": { "$ref": "#/$defs/provider" },
+              "model": { "type": "string", "minLength": 1 },
+              "effort": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "thresholdBand": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "act": { "type": "number", "minimum": 0, "maximum": 1 },
+        "check": { "type": "number", "minimum": 0, "maximum": 1 },
+        "close_margin": { "type": "number", "minimum": 0, "maximum": 1 }
+      }
+    },
+    "argvOrNull": {
+      "anyOf": [
+        { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+        { "type": "null" }
+      ]
+    }
+  }
+}

package/schema/facts.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://code-forge.dev/schema/facts.schema.json",
+  "title": "code-forge facts delegate answer",
+  "description": "Plan v1.3 §3.8 step 3: the L0 facts delegate's answer. One row per claim token: the read-only command it ran, the output line it quotes, and a tag. A VERIFIED row must quote a non-empty excerpt; `why` says why a claim is UNVERIFIABLE (null otherwise).",
+  "type": "object",
+  "properties": {
+    "facts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "fact_id": { "type": "string", "pattern": "^F[0-9]+$" },
+          "claim": { "type": "string", "minLength": 1 },
+          "kind": { "type": "string", "enum": ["flag", "command", "path", "version", "endpoint", "package", "env"] },
+          "command": { "type": "string" },
+          "output_excerpt": { "type": "string", "maxLength": 200 },
+          "tag": { "type": "string", "enum": ["VERIFIED", "NOT-FOUND", "UNVERIFIABLE"] },
+          "why": { "type": ["string", "null"] }
+        },
+        "required": ["fact_id", "claim", "kind", "command", "output_excerpt", "tag", "why"],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": ["facts"],
+  "additionalProperties": false
+}