specrails-core 6.0.0 → 6.0.1

package/dist/agent-runtime/verification-plan.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { bindVerificationPlan, pipelineStateDirectory, validateVerificationRequest } from '../pipeline/pipeline-state.js';
+import { assertProposalInScope, withScopeDefault } from './change-scope.js';
 import { fingerprint } from './durable-store.js';
 import { child, write } from './graph/artifacts.js';
 const SAFE_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
@@ -39,7 +40,10 @@ export function validateProposedChecks(context, raw) {
         text(check.command, 'command', 4096);
         if (!Array.isArray(check.args) || check.args.length > 128 || check.args.some(arg => typeof arg !== 'string' || arg.includes('\0') || arg.length > 4096))
             throw new Error('Invalid verification proposal args');
-        validateVerificationRequest(context, { kind: 'scoped', commands: [check] });
+        if (check.cwd !== undefined && typeof check.cwd !== 'string')
+            throw new Error('Invalid verification proposal cwd');
+        assertProposalInScope(context, check);
+        validateVerificationRequest(context, { kind: 'scoped', commands: [withScopeDefault(context, check)] });
         if (check.kind === 'command') {
             if (check.entrypoint !== undefined || check.files !== undefined)
                 throw new Error('Invalid command proposal: harness fields are forbidden');
@@ -123,7 +127,8 @@ export function readVerificationPlan(context) {
 }
 export function initializeVerificationPlan(context, host, architect, maxConcurrency = 1) {
     const previous = readVerificationPlan(context);
-    const baseline = [['host', host], ['architect', architect]].flatMap(([origin, commands]) => commands.map((command, i) => entry(`${origin}:${command.key ?? `${i}-${fingerprint(normalized(command)).slice(0, 12)}`}`, command.label ?? [command.command, ...command.args].join(' ').slice(0, 256), command, origin)));
+    // The key hashes the command as declared, so a scope default never renames a check.
+    const baseline = [['host', host], ['architect', architect]].flatMap(([origin, commands]) => commands.map((command, i) => entry(`${origin}:${command.key ?? `${i}-${fingerprint(normalized(command)).slice(0, 12)}`}`, command.label ?? [command.command, ...command.args].join(' ').slice(0, 256), withScopeDefault(context, command), origin)));
     if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 4)
         throw new Error('Invalid verification concurrency');
     if (previous && fingerprint(previous.baseline) !== fingerprint(baseline))
@@ -156,7 +161,7 @@ export function addDeveloperChecks(context, proposals) {
     const developer = new Map(previous.developer.map(item => [item.key, item]));
     const sources = [];
     for (const check of checked) {
-        const command = { repositoryId: check.repositoryId, command: check.command, args: check.args, ...(check.cwd === undefined ? {} : { cwd: check.cwd }), ...(check.timeoutMs === undefined ? {} : { timeoutMs: check.timeoutMs }) };
+        const command = withScopeDefault(context, { repositoryId: check.repositoryId, command: check.command, args: check.args, ...(check.cwd === undefined ? {} : { cwd: check.cwd }), ...(check.timeoutMs === undefined ? {} : { timeoutMs: check.timeoutMs }) });
         const files = check.files?.slice().sort((a, b) => a.path.localeCompare(b.path)).map(file => ({ path: file.path, hash: bytesHash(file.content), byteCount: Buffer.byteLength(file.content) }));
         const harness = files ? { hash: fingerprint(files), entrypoint: check.entrypoint, sources: files } : undefined;
         const item = entry('dev:' + check.key, check.label, command, 'developer', harness);

package/dist/pipeline/pipeline-state.d.ts

@@ -7,11 +7,18 @@ export interface PipelineSpec {
     repositoryIds?: string[];
     acceptanceCriteria?: string[];
 }
+/**
+ * `scope`: checkout-relative directories the repository is confined to — a
+ * package registered inside a larger checkout (a monorepo app). Edits outside
+ * them are not part of the change, and a command without `cwd` runs in the
+ * first one. Absent: the whole checkout is the repository.
+ */
 export interface PipelineRepository {
     id: string;
     name: string;
     path: string;
     baseSha?: string;
+    scope?: string[];
 }
 export interface PipelineContext {
     schemaVersion: 1;
@@ -194,6 +201,10 @@ export interface PreviewFile {
     contentHash?: string;
 }
 export declare function verificationEnvironment(env: NodeJS.ProcessEnv, overrides?: Record<string, string>, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
+/** True when a checkout-relative POSIX path belongs to the repository's scope (always, without a scope). */
+export declare function withinRepositoryScope(repository: Pick<PipelineRepository, 'scope'>, relative: string): boolean;
+/** Where a command without `cwd` runs: the first scope directory, else the checkout root. */
+export declare function repositoryWorkingDirectory(repository: Pick<PipelineRepository, 'path' | 'scope'>): string;
 export declare function validatePipelineContext(input: unknown): PipelineContext;
 export declare function pipelineStateDirectory(context: PipelineContext): string;
 export interface CandidateManifest {

package/dist/pipeline/pipeline-state.js

@@ -83,6 +83,58 @@ function safeChild(root, relative) {
     }
     return target;
 }
+/** Case-insensitive filesystems: compare checkout paths the way the OS resolves them. */
+const foldedPaths = process.platform === 'win32' || process.platform === 'darwin';
+function samePathPrefix(file, directory) {
+    const [a, b] = foldedPaths ? [file.toLowerCase(), directory.toLowerCase()] : [file, directory];
+    return a === b || a.startsWith(b + '/');
+}
+/** Normalized scope: existing, symlink-free directories spelled as on disk. Undefined = whole checkout. */
+function repositoryScope(root, raw) {
+    if (!Array.isArray(raw) || raw.length === 0 || raw.length > 32)
+        fail('Invalid repository scope: expected 1–32 directories');
+    const scope = [];
+    for (const value of raw) {
+        if (typeof value !== 'string' || !value.trim() || value.includes('\0') || value.length > 1024)
+            fail('Invalid repository scope directory');
+        const relative = value.replace(/\\/g, '/').replace(/^(?:\.\/)+/, '').replace(/\/+$/, '');
+        // The checkout root is the whole repository: no narrower scope applies.
+        if (!relative || relative === '.')
+            return undefined;
+        if (/^[a-z]:/i.test(relative) || relative.startsWith('/') || relative.split('/').some(part => !part || part === '.' || part === '..'))
+            fail('Invalid repository scope directory: ' + value);
+        // Spell every component as the directory listing does, so git paths match it.
+        let current = root;
+        const parts = [];
+        for (const part of relative.split('/')) {
+            let name = part;
+            try {
+                const names = readdirSync(current);
+                if (!names.includes(part))
+                    name = names.find(entry => entry.toLowerCase() === part.toLowerCase()) ?? part;
+            }
+            catch { /* the lstat below reports the missing directory */ }
+            current = path.join(current, name);
+            const stat = lstatSync(current, { throwIfNoEntry: false });
+            if (!stat)
+                fail('Repository scope directory does not exist: ' + value);
+            if (stat.isSymbolicLink() || !stat.isDirectory())
+                fail('Repository scope must be a real directory: ' + value);
+            parts.push(name);
+        }
+        scope.push(parts.join('/'));
+    }
+    const unique = [...new Set(scope)];
+    return unique.filter(item => !unique.some(other => other !== item && samePathPrefix(item, other)));
+}
+/** True when a checkout-relative POSIX path belongs to the repository's scope (always, without a scope). */
+export function withinRepositoryScope(repository, relative) {
+    return !repository.scope?.length || repository.scope.some(directory => samePathPrefix(relative, directory));
+}
+/** Where a command without `cwd` runs: the first scope directory, else the checkout root. */
+export function repositoryWorkingDirectory(repository) {
+    return repository.scope?.length ? path.join(repository.path, ...repository.scope[0].split('/')) : repository.path;
+}
 function atomicJson(file, value) {
     mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
     const temp = file + '.' + randomUUID() + '.tmp';
@@ -106,7 +158,9 @@ export function validatePipelineContext(input) {
             fail('Invalid repository identity');
         if (repo.baseSha !== undefined && (typeof repo.baseSha !== 'string' || !/^[a-f0-9]{40,64}$/.test(repo.baseSha)))
             fail('Invalid repository base SHA');
-        return { id: repo.id, name: repo.name, path: directory(repo.path), ...(repo.baseSha ? { baseSha: repo.baseSha } : {}) };
+        const root = directory(repo.path);
+        const scope = repo.scope === undefined ? undefined : repositoryScope(root, repo.scope);
+        return { id: repo.id, name: repo.name, path: root, ...(repo.baseSha ? { baseSha: repo.baseSha } : {}), ...(scope ? { scope } : {}) };
     });
     if (new Set(repositories.map((repo) => repo.id)).size !== repositories.length || new Set(repositories.map((repo) => repo.path)).size !== repositories.length)
         fail('Duplicate repository identity or path');
@@ -711,7 +765,7 @@ function validateCommand(context, raw) {
     const repo = context.repositories.find((item) => item.id === command.repositoryId);
     if (!repo || typeof command.command !== 'string' || !command.command || command.command.includes('\0') || !Array.isArray(command.args) || !command.args.every((arg) => typeof arg === 'string' && !arg.includes('\0')))
         fail('Invalid verification command');
-    const cwd = command.cwd === undefined ? repo.path : directory(path.resolve(repo.path, String(command.cwd)));
+    const cwd = command.cwd === undefined ? directory(repositoryWorkingDirectory(repo)) : directory(path.resolve(repo.path, String(command.cwd)));
     if (!within(repo.path, cwd))
         fail('Verification cwd escapes selected repository');
     const env = command.env === undefined ? undefined : object(command.env);

package/integration-contract.json

@@ -289,7 +289,7 @@
   "execution": {
     "schemaVersion": 1,
     "contextEnv": "SPECRAILS_EXECUTION_CONTEXT",
-    "context": "Absolute JSON file: runId, backlogRoot, backlogPath?, artifactRoot, artifactRepositoryId, repositories[{id,name,path,baseSha?}], ownership{git,backlog,worktrees:host|core}, specs[{id,title,description,repositoryIds?,acceptanceCriteria?}]",
+    "context": "Absolute JSON file: runId, backlogRoot, backlogPath?, artifactRoot, artifactRepositoryId, repositories[{id,name,path,baseSha?,scope?}], ownership{git,backlog,worktrees:host|core}, specs[{id,title,description,repositoryIds?,acceptanceCriteria?}]. scope (runtime capability repositoryScope) lists the checkout-relative directories a repository is confined to — a package registered inside a larger checkout: commands without cwd run in the first one, model-proposed checks stay inside it, edits outside it are undone after each developer/fixer turn and reviews judge the git change set against the run base.",
     "runtime": ".specrails/runtime/pipeline.mjs",
     "operations": [
       "init",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "6.0.0",
+  "version": "6.0.1",
   "description": "Agent workflow engine for specrails-desktop: provider-independent installer and programmatic agent runtime for Claude Code, Codex, Gemini CLI and Kimi Code",
   "type": "module",
   "exports": {