@ps-neko/nekowork 0.2.0-alpha.6 → 0.2.0-alpha.8

package/LICENSE

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

package/README.md

@@ -4,9 +4,21 @@
 
 AI can write 100 lines in 10 seconds. Who checks them before they hit `main`?
 
-This package reviews every change your AI tool makes, flags the risky parts with
-deterministic rules, and lets **you** make the final call. It never commits,
-pushes, or deploys on its own.
+This package reviews every change your AI tool makes, **flags a defined set of
+AI-introduced risk patterns** (11 deterministic rules: secrets, secret fallbacks,
+hardcoded credentials, auto-push/commit, test/security disables, risky package
+hooks, eval, insecure TLS, CORS wildcard, basic SQL/command injection, and AST
+dataflow taint for variable-mediated injection) and routes everything else to a
+human decision. It is **not an exhaustive security audit** — the AST rule is
+intraprocedural (single-function, JS/TS); cross-function and whole-program dataflow
+are out of scope. The verdict is deterministic (same diff, same result), and it never
+commits, pushes, or deploys on its own. **You** make the final call.
+
+> Note: the published `@alpha` (0.2.0-alpha.7) now ships all **11 rules** described
+> above (incl. eval, insecure TLS, CORS wildcard, SQL/command injection, AST dataflow)
+> and adds **one tiny, well-known dependency** (`acorn`, the JS parser — MIT, zero
+> transitive dependencies) for the AST engine. Always install with the **`@alpha`**
+> tag: the `latest` dist-tag is a stale `0.2.0-alpha.0` (5 rules, zero deps).
 
 ## Status
 
@@ -33,14 +45,21 @@ npx -y @ps-neko/nekowork@alpha verify-pr    # scan the diff → get a verdict
 `verify-pr` reads the diff, writes a plain-English `REPORT.md`, and tells you
 whether the change is safe to merge.
 
-## The 4 verbs
+## The verbs
+
+**Primary — the 1.0 front surface. Start here:**
 
 | Verb | What it does |
 |---|---|
 | `check` | Probe environment readiness (Node version, git repo, etc.) |
-| `verify-pr` | Scan working-tree diff. Produce REPORT.md + .nekowork/decision.json |
-| `report` | Session-based compatibility command. Requires `--session <id>` and renders that session's evidence to REPORT.md. The normal `verify-pr` path already writes REPORT.md directly — you don't need `report` for it. |
-| `apply` | Session-based compatibility apply. Requires a completed work cycle (SHIP_READY marker + cleared Human Gate). NOT driven by verify-pr's decision.json. See [ADVANCED.md](https://github.com/Ps-Neko/NEKOWORK/blob/main/packages/nekowork-cli/docs/ADVANCED.md). |
+| `verify-pr` | Scan the working-tree diff. Produce REPORT.md + .nekowork/decision.json |
+
+**Compatibility — session-based (legacy/advanced; not needed for the normal flow):**
+
+| Verb | What it does |
+|---|---|
+| `report --session <id>` | Render that session's evidence to REPORT.md. The normal `verify-pr` path already writes REPORT.md directly — you don't need `report` for it. |
+| `apply --session <id>` | Apply a stored `.diff`. Requires a completed work cycle (SHIP_READY marker + cleared Human Gate). NOT driven by verify-pr's decision.json. See [ADVANCED.md](https://github.com/Ps-Neko/NEKOWORK/blob/main/packages/nekowork-cli/docs/ADVANCED.md). |
 
 Anything else (`ask`, `plan`, `team`, `work`, `ship`, `build`, `auto`,
 `pr-prep`, `review`, ...) belongs to `@ps-neko/nekowork-harness` (legacy and
@@ -66,7 +85,7 @@ step — it is not triggered by `decision.json`.
 
 - [Quickstart](https://github.com/Ps-Neko/NEKOWORK/blob/main/packages/nekowork-cli/docs/QUICKSTART.md)
 - [How verification works](https://github.com/Ps-Neko/NEKOWORK/blob/main/packages/nekowork-cli/docs/SCOPE-1.0.md)
-- [Benchmark](https://github.com/Ps-Neko/NEKOWORK/blob/main/packages/nekowork-cli/docs/BENCHMARK.md) — 85/86 (99%) recall, 0/47 FP, 30 real OSS positives (secret-fallback)
+- [Benchmark](https://github.com/Ps-Neko/NEKOWORK/blob/main/packages/nekowork-cli/docs/BENCHMARK.md) — 11 rules, 184/184 (100%) recall, 0/120 FP; 30 real OSS positives on `secret-fallback`, the newer rules (incl. sql/command injection and `ast-dataflow`) are synthetic-only
 - [Integration](https://github.com/Ps-Neko/NEKOWORK/blob/main/packages/nekowork-cli/docs/INTEGRATION.md)
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ps-neko/nekowork",
-  "version": "0.2.0-alpha.6",
+  "version": "0.2.0-alpha.8",
   "description": "Local verification gate for AI-written code diffs. Deterministic rules decide the verdict, never the LLM. No auto-commit, push, or deploy — you decide at the Human Gate.",
   "keywords": [
     "ai-code-review",
@@ -33,7 +33,11 @@
     "nekowork": "scripts/cli.js"
   },
   "files": [
-    "scripts/",
+    "scripts/cli.js",
+    "scripts/check.js",
+    "scripts/core/",
+    "scripts/lib/",
+    "scripts/orchestrators/",
     "README.md",
     "LICENSE"
   ],
@@ -43,5 +47,7 @@
     "test": "node --test tests/unit/*.test.js",
     "bench:rules": "node scripts/benchmark/rules.js"
   },
-  "dependencies": {}
+  "dependencies": {
+    "acorn": "^8.16.0"
+  }
 }

package/scripts/cli.js

@@ -13,8 +13,6 @@ import {
   verifyPrCycle,
   parseVerifyPrArgs,
   printVerifyPrSummary,
-  EXIT_CODE,
-  VERDICT,
 } from './orchestrators/verify-pr.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -38,6 +36,7 @@ verify-pr options:
   --from-staged             scan staged diff
   --range <baseSha...head>  scan commit range
   --from-patch <file>       scan a patch file
+  --full-scan               scan the whole tree (onboarding; no PR/diff yet)
   --include <path>          force-scan a path even if gitignored
   --comment-file <path>     write a PR-comment markdown
   --ci-exit-soft            NEEDS_HUMAN_REVIEW / INSUFFICIENT_EVIDENCE → exit 0
@@ -93,7 +92,20 @@ async function runInternal(verb, rest) {
 
   if (verb === 'verify-pr') {
     const opts = parseVerifyPrArgs(rest);
-    const result = await verifyPrCycle(opts);
+    let result;
+    try {
+      result = await verifyPrCycle(opts);
+    } catch (e) {
+      const msg = String(e?.message || e);
+      if (/not a git repository/i.test(msg)) {
+        console.error('verify-pr could not find a git repository here.');
+        console.error('  Run it inside a git repo, or scan a patch file instead:');
+        console.error('    nekowork verify-pr --from-patch <file>');
+        process.exit(2);
+      }
+      console.error(msg);
+      process.exit(1);
+    }
     if (opts.json) {
       console.log(JSON.stringify({
         decision: result.decision,
@@ -104,11 +116,9 @@ async function runInternal(verb, rest) {
     } else {
       printVerifyPrSummary(result);
     }
-    let exitCode = EXIT_CODE[result.decision.verdict] ?? 1;
-    if (opts.ciExitSoft && (result.decision.verdict === VERDICT.NEEDS_HUMAN_REVIEW || result.decision.verdict === VERDICT.INSUFFICIENT_EVIDENCE)) {
-      exitCode = 0;
-    }
-    process.exit(exitCode);
+    // Single source of truth: verifyPrCycle already computed exitCode and
+    // honored --ci-exit-soft. Do not recompute here.
+    process.exit(result.exitCode ?? 1);
   }
 
   if (verb === 'report') {

package/scripts/core/git-mutation-guard.js

@@ -47,6 +47,71 @@ export async function withGitMutationGuard(root, fn, options = {}) {
   return result;
 }
 
+/**
+ * Synchronous mutation guard for `apply`: the apply step DOES legitimately
+ * mutate the working tree, so a blunt before≠after check is wrong here. Instead
+ * we sanction the EXPECTED files (the diff's own files) and reject only changes
+ * to git-tracked paths OUTSIDE that set — i.e. an unexpected EXTRA mutation
+ * (a stray commit/checkout/branch op or an edit to an unrelated file the apply
+ * was not supposed to touch).
+ *
+ * Behavior-preserving: when only the expected files changed (the normal case)
+ * this returns fn()'s result unchanged. No-op outside a git worktree or when
+ * `allowEnvKey` is set to '1'.
+ *
+ * @param {string} root
+ * @param {() => T} fn  synchronous function performing the apply
+ * @param {object} [options]
+ * @param {string[]} [options.expectedPaths]  repo-relative paths the apply may touch
+ * @param {string} [options.label]
+ * @param {string} [options.allowEnvKey]
+ * @param {NodeJS.ProcessEnv} [options.env]
+ * @returns {T}
+ * @template T
+ */
+export function withGitMutationGuardSync(root, fn, options = {}) {
+  const label = options.label || 'apply';
+  const allowEnvKey = options.allowEnvKey || 'HARNESS_ALLOW_WORKSPACE_MUTATION';
+  const env = options.env || process.env;
+  const expected = new Set((options.expectedPaths || []).map(p => String(p).split('\\').join('/')));
+
+  if (!root || env[allowEnvKey] === '1' || !isGitWorkTree(root)) {
+    return fn();
+  }
+
+  const beforeSet = changedPathSet(root);
+  const result = fn();
+  const afterSet = changedPathSet(root);
+
+  const unexpected = [...afterSet].filter(p => !beforeSet.has(p) && !expected.has(p));
+  if (unexpected.length) {
+    throw new Error([
+      `${label} produced unexpected git changes outside the applied diff.`,
+      `Set ${allowEnvKey}=1 only when these extra mutations are intentional.`,
+      '',
+      'Unexpected paths:',
+      ...unexpected.map(p => `  ${p}`),
+    ].join('\n'));
+  }
+  return result;
+}
+
+function changedPathSet(root) {
+  const text = runGit(root, ['status', '--porcelain=v1']);
+  const set = new Set();
+  for (const line of (text || '').split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    // porcelain v1: "XY <path>" (and "XY <old> -> <new>" for renames).
+    let p = line.slice(3).trim();
+    const arrow = p.indexOf(' -> ');
+    if (arrow !== -1) p = p.slice(arrow + 4);
+    // strip optional surrounding quotes git adds for unusual paths
+    p = p.replace(/^"(.*)"$/, '$1').split('\\').join('/');
+    set.add(p);
+  }
+  return set;
+}
+
 export function readGitStatus(root) {
   if (!isGitWorkTree(root)) return null;
 

package/scripts/lib/acceptance-criteria.js

@@ -1,5 +1,7 @@
+// Shared library module — consumed by the heavy @ps-neko/nekowork-harness package; kept in slim as the single source of truth.
 import fs from 'node:fs';
 import path from 'node:path';
+import { readJson } from './session-io.js';
 
 const DEFAULT_COUNT = 3;
 
@@ -94,12 +96,3 @@ export function buildDefaultAcceptanceCriteria(task = '', minimum = DEFAULT_COUN
     source: 'task-derived-minimum',
   }));
 }
-
-function readJson(file) {
-  if (!fs.existsSync(file)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(file, 'utf8'));
-  } catch {
-    return null;
-  }
-}