@voidlabs.gg/voidshift-agents 0.5.0 → 0.6.0

package/dist/index.js

@@ -4,7 +4,7 @@ import { homedir } from 'node:os';
 import { basename, dirname, join, resolve, sep } from 'node:path';
 import { parseArgs } from 'node:util';
 import { fileURLToPath } from 'node:url';
-import { AGENTS, AGENT_FILE, STEPS, TEMPLATES, isProducer, agentFolders, agentsDir, describeSteps, describeTrigger, describeTriggers, describeWorkflow, stepEnabled, stepId, visibleAgents, readAgentsConfig, writeAgentsConfig, DEFAULTS } from "./config.js";
+import { AGENTS, AGENT_FILE, STEPS, TEMPLATES, isProducer, agentFolders, agentsDir, describeSteps, describeTrigger, describeTriggers, describeWorkflow, stepEnabled, stepId, visibleAgents, readAgentsConfig, writeAgentsConfig, workspaceOf, DEFAULTS, DEFAULT_WORKSPACE, WORKSPACE_NAME } from "./config.js";
 import { controlChecks, controlCommands, controlUsage } from "./control.js";
 import { keyStore, looksLikeLinearKey, readLinearKey, readSecret, storeLinearKey, storeSecret } from "./secrets.js";
 import { TRACKERS } from "./tracker.js";
@@ -14,7 +14,7 @@ import { trackersInUse } from "./control.js";
 import { runnerService } from "./service.js";
 import { initProfile, profileChecks, profileDir, readRules, renderClaudeSettings, CLAUDE_SETTINGS, RULES_FILE } from "./profile.js";
 import { createLinear } from "./linear.js";
-import { TRIGGER_FORMS, duplicateTriggerWarnings, moveKey, parseTrigger, renameKey, sameTrigger, validateAgentFolder, validateConfig, validateWorkflow, workflowsUsing } from "./manage.js";
+import { TRIGGER_FORMS, duplicateTriggerWarnings, moveKey, parseTrigger, projectProblems, renameKey, sameTrigger, validateAgentFolder, validateConfig, validateWorkflow, workflowsUsing } from "./manage.js";
 import { parseStep, resolveName, stepNames } from "./names.js";
 import { findRepos } from "./repos.js";
 import { defaultBranch, sh } from "./git.js";
@@ -239,7 +239,8 @@ async function promptProject(ui, config, current = {}, edit = false, allowExisti
 const describeProject = (config, name) => {
     const p = config.projects[name];
     const used = workflowsUsing(config, name);
-    return `${name}  ${tilde(p.path)}, PRs into ${p.base ?? 'the default branch'}, ${used.length ? `used by ${used.join(', ')}` : 'not used by any workflow'}`;
+    const where = [p.workspace ? `workspace ${p.workspace}` : '', p.match?.length ? `matches ${p.match.join(', ')}` : ''].filter(Boolean);
+    return `${name}  ${tilde(p.path)}, PRs into ${p.base ?? 'the default branch'}, ${where.map((w) => `${w}, `).join('')}${used.length ? `used by ${used.join(', ')}` : 'not used by any workflow'}`;
 };
 // Named local repos the workflows run in. Triggers point at them by name.
 async function setupProjects(ui, config, log) {
@@ -366,11 +367,14 @@ const USAGE = [
     ['workflow rm NAME [--yes]', 'Delete a workflow'],
     ['workflow move NAME (--first | --last | --before OTHER | --after OTHER)', 'Change the match order'],
     ['projects [--json]', 'List projects'],
-    ['project add [NAME] [--path P] [--base B]', 'Add a project; prompts for what is missing'],
+    ['project add [NAME] [--path P] [--base B] [--workspace W] [--match NAME]...', 'Add a project; prompts for what is missing. --match routes cards of that tracker project here, whatever the workflow says'],
     ['project show NAME [--json]', 'Show one project'],
-    ['project edit NAME [--path P] [--base B]', 'Change a project; no flags asks'],
+    ['project edit NAME [--path P] [--base B] [--workspace W] [--match NAME]...', 'Change a project; no flags asks. An empty --workspace or --match clears it'],
     ['project rename OLD NEW', 'Rename a project and the workflows that use it'],
     ['project rm NAME [--yes]', 'Delete a project nothing uses'],
+    ['workspace add NAME --root DIR [--context FILE]', 'Add a workspace: a folder of repos with its own run queue. Steps carry FILE, or DIR/CONTEXT.md'],
+    ['workspace list [--json]', 'List workspaces and their projects'],
+    ['workspace rm NAME', 'Delete a workspace no project uses'],
     ['homes [--json]', 'Show where the agents are linked'],
     ['link DIR [--claude | --codex]', 'Link the agents into a config folder'],
     ['unlink DIR', 'Remove the agents from a config folder'],
@@ -789,9 +793,31 @@ function pickProject(config, input, ctx) {
     }
     return r.name;
 }
+const PROJECT_FLAGS = { path: { type: 'string' }, base: { type: 'string' }, workspace: { type: 'string' }, match: { type: 'string', multiple: true } };
+// Applies --workspace and --match to a project. An empty value clears either.
+// Returns a complaint when the workspace or a match does not fit.
+function applyWorkspaceFlags(config, name, project, v) {
+    if (v.workspace !== undefined) {
+        const ws = String(v.workspace).trim();
+        if (ws && ws !== DEFAULT_WORKSPACE && !config.workspaces[ws])
+            return `No workspace named ${ws}. vsf agents workspace add creates it.`;
+        if (ws && ws !== DEFAULT_WORKSPACE)
+            project.workspace = ws;
+        else
+            delete project.workspace;
+    }
+    if (v.match !== undefined) {
+        const match = v.match.map((m) => m.trim()).filter(Boolean);
+        if (match.length)
+            project.match = match;
+        else
+            delete project.match;
+    }
+    return projectProblems({ ...config.projects, [name]: project }, config.workspaces)[0] ?? null;
+}
 const projectSubs = {
     async add(args, ctx) {
-        const p = begin('project add', args, { path: { type: 'string' }, base: { type: 'string' } }, ctx);
+        const p = begin('project add', args, PROJECT_FLAGS, ctx);
         if (typeof p === 'number')
             return p;
         if (p.positionals.length > 1) {
@@ -838,6 +864,11 @@ const projectSubs = {
             name = r.name;
             project = r.project;
         }
+        const bad = applyWorkspaceFlags(config, name, project, p.values);
+        if (bad) {
+            ctx.log(bad);
+            return 1;
+        }
         config.projects[name] = project;
         save(ctx, config);
         ctx.log(`Project ${name}: ${tilde(project.path)}${project.base ? `, PRs into ${project.base}` : ''}`);
@@ -861,12 +892,15 @@ const projectSubs = {
             ctx.log(`Project ${name}`);
             ctx.log(`Path: ${tilde(proj.path)}`);
             ctx.log(`PRs into: ${proj.base ?? 'the default branch'}`);
+            ctx.log(`Workspace: ${workspaceOf(proj)}`);
+            if (proj.match?.length)
+                ctx.log(`Matches: ${proj.match.join(', ')}`);
             ctx.log(`Used by: ${used.length ? used.join(', ') : 'no workflows'}`);
         }
         return 0;
     },
     async edit(args, ctx) {
-        const p = begin('project edit', args, { path: { type: 'string' }, base: { type: 'string' } }, ctx);
+        const p = begin('project edit', args, PROJECT_FLAGS, ctx);
         if (typeof p === 'number')
             return p;
         if (!needArgs(p, 1, 'project edit', ctx))
@@ -877,9 +911,9 @@ const projectSubs = {
             return 1;
         const current = config.projects[name];
         const v = p.values;
-        if (v.path === undefined && v.base === undefined) {
+        if (v.path === undefined && v.base === undefined && v.workspace === undefined && v.match === undefined) {
             if (!interactive()) {
-                ctx.log('Nothing to change. Give --path or --base, or run this in a terminal to be asked.');
+                ctx.log('Nothing to change. Give --path, --base, --workspace or --match, or run this in a terminal to be asked.');
                 ctx.log(usageOf('project edit'));
                 return 2;
             }
@@ -887,7 +921,8 @@ const projectSubs = {
         }
         else {
             const path = v.path !== undefined ? resolve(expandHome(v.path)) : current.path;
-            if (!isRepo(path)) {
+            // Only a new path needs checking; a workspace or match change keeps the repo.
+            if (v.path !== undefined && !isRepo(path)) {
                 ctx.log(`${tilde(path)} is not a git repository.`);
                 return 1;
             }
@@ -899,6 +934,11 @@ const projectSubs = {
                 else
                     delete next.base;
             }
+            const bad = applyWorkspaceFlags(config, name, next, v);
+            if (bad) {
+                ctx.log(bad);
+                return 1;
+            }
             config.projects[name] = next;
         }
         save(ctx, config);
@@ -960,6 +1000,87 @@ const projectSubs = {
         return 0;
     },
 };
+// ---- workspaces ----
+const projectsIn = (config, ws) => Object.entries(config.projects).filter(([, p]) => workspaceOf(p) === ws).map(([n]) => n);
+const workspaceSubs = {
+    async add(args, ctx) {
+        const p = begin('workspace add', args, { root: { type: 'string' }, context: { type: 'string' } }, ctx);
+        if (typeof p === 'number')
+            return p;
+        if (!needArgs(p, 1, 'workspace add', ctx))
+            return 2;
+        const name = p.positionals[0].trim();
+        if (!WORKSPACE_NAME.test(name)) {
+            ctx.log('A workspace name is letters, digits, dashes and underscores.');
+            return 2;
+        }
+        if (!p.values.root) {
+            ctx.log('Missing --root.');
+            ctx.log(usageOf('workspace add'));
+            return 2;
+        }
+        const config = readAgentsConfig(ctx.configDir);
+        if (config.workspaces[name]) {
+            ctx.log(`A workspace named ${name} already exists.`);
+            return 1;
+        }
+        const root = resolve(expandHome(p.values.root));
+        if (!existsSync(root)) {
+            ctx.log(`${tilde(root)} does not exist.`);
+            return 1;
+        }
+        const context = p.values.context ? resolve(root, expandHome(p.values.context)) : undefined;
+        if (context && !existsSync(context)) {
+            ctx.log(`${tilde(context)} does not exist.`);
+            return 1;
+        }
+        config.workspaces[name] = { root, ...(context ? { context } : {}) };
+        save(ctx, config);
+        ctx.log(`Workspace ${name}: ${tilde(root)}. vsf agents project edit P --workspace ${name} puts a project in it.`);
+        return 0;
+    },
+    async list(args, ctx) {
+        const p = begin('workspace list', args, { json: { type: 'boolean' } }, ctx);
+        if (typeof p === 'number')
+            return p;
+        const config = readAgentsConfig(ctx.configDir);
+        const names = [...new Set([...Object.keys(config.workspaces), ...Object.values(config.projects).map(workspaceOf)])];
+        if (p.values.json) {
+            out(ctx, names.map((name) => ({ name, ...config.workspaces[name], projects: projectsIn(config, name) })));
+            return 0;
+        }
+        if (!names.length)
+            ctx.log('No workspaces yet. Every project runs in the default one; vsf agents workspace add creates another.');
+        for (const name of names) {
+            const w = config.workspaces[name];
+            const projects = projectsIn(config, name);
+            ctx.log(`${name}  ${w ? tilde(w.root) : 'no root'}${w?.context ? `, context ${tilde(w.context)}` : ''}, ${projects.length ? projects.join(', ') : 'no projects'}`);
+        }
+        return 0;
+    },
+    async rm(args, ctx) {
+        const p = begin('workspace rm', args, {}, ctx);
+        if (typeof p === 'number')
+            return p;
+        if (!needArgs(p, 1, 'workspace rm', ctx))
+            return 2;
+        const config = readAgentsConfig(ctx.configDir);
+        const name = p.positionals[0].trim();
+        if (!config.workspaces[name]) {
+            ctx.log(`No workspace named ${name}.`);
+            return 1;
+        }
+        const used = projectsIn(config, name);
+        if (used.length) {
+            ctx.log(`Used by ${used.join(', ')}. Move those projects first: vsf agents project edit P --workspace OTHER.`);
+            return 1;
+        }
+        delete config.workspaces[name];
+        save(ctx, config);
+        ctx.log(`Deleted workspace ${name}.`);
+        return 0;
+    },
+};
 // ---- homes ----
 // Per enabled agent: ours, taken by something else, or missing.
 function homeReport(config, h) {
@@ -1242,6 +1363,7 @@ const agents = {
             return 0;
         },
         project: (args, ctx) => group('project', projectSubs, args, ctx),
+        workspace: (args, ctx) => group('workspace', workspaceSubs, args, ctx),
         homes: homeCommands.homes,
         link: homeCommands.link,
         unlink: homeCommands.unlink,

package/dist/manage.d.ts

@@ -18,4 +18,5 @@ export type Place = {
 };
 export declare function moveKey<T>(record: Record<string, T>, name: string, place: Place): Record<string, T>;
 export declare const workflowsUsing: (config: Pick<AgentsConfig, "workflows">, project: string) => string[];
-export declare function validateConfig(value: unknown, saved?: Pick<AgentsConfig, 'projects' | 'workflows'>): string[];
+export declare function projectProblems(projects: AgentsConfig['projects'], workspaces: AgentsConfig['workspaces']): string[];
+export declare function validateConfig(value: unknown, saved?: Pick<AgentsConfig, 'projects' | 'workflows'> & Partial<Pick<AgentsConfig, 'workspaces'>>): string[];

package/dist/manage.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
-import { AGENTS, AGENT_FILE, OUTPUTS, STEP_ID, isBuiltin, readAgentFolder, stepFile, describeTrigger, triggerSpec } from "./config.js";
+import { AGENTS, AGENT_FILE, DEFAULT_WORKSPACE, OUTPUTS, STEP_ID, WORKSPACE_NAME, isBuiltin, readAgentFolder, stepFile, describeTrigger, triggerSpec } from "./config.js";
 import { parseCron } from "./cron.js";
 const isInt = (v, min, max) => typeof v === 'number' && Number.isInteger(v) && v >= min && v <= max;
 // The line a step's prompt must ask for, so the runner can read the result.
@@ -185,6 +185,34 @@ export function moveKey(record, name, place) {
 }
 export const workflowsUsing = (config, project) => Object.entries(config.workflows).filter(([, w]) => w.project === project).map(([n]) => n);
 const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+// What is wrong with the projects' workspaces and matches: a workspace that
+// does not exist, or a tracker project name two projects both claim.
+export function projectProblems(projects, workspaces) {
+    const problems = [];
+    const claimed = new Map();
+    for (const [name, p] of Object.entries(projects)) {
+        if (!isObj(p))
+            continue;
+        if (p.workspace !== undefined && (typeof p.workspace !== 'string' || (p.workspace !== DEFAULT_WORKSPACE && !Object.hasOwn(workspaces, p.workspace)))) {
+            problems.push(`Project ${name}: workspace ${String(p.workspace)} does not exist. vsf agents workspace add creates it.`);
+        }
+        if (p.match === undefined)
+            continue;
+        if (!Array.isArray(p.match) || p.match.some((m) => typeof m !== 'string' || !m.trim())) {
+            problems.push(`Project ${name}: match must list tracker project names.`);
+            continue;
+        }
+        for (const m of p.match) {
+            const key = m.trim().toLowerCase();
+            const other = claimed.get(key);
+            if (other && other !== name)
+                problems.push(`Projects ${other} and ${name} both match ${m}.`);
+            else
+                claimed.set(key, name);
+        }
+    }
+    return problems;
+}
 // Everything wrong with a whole agents config, e.g. one edited by hand.
 // `saved` is the config on disk: only what the write changes is checked, so a
 // moved folder or a retired agent elsewhere does not block an unrelated edit.
@@ -209,6 +237,23 @@ export function validateConfig(value, saved) {
         else if (saved?.projects?.[name]?.path !== p.path && !existsSync(join(p.path, '.git')))
             problems.push(`Project ${name}: ${p.path} is not a git repository.`);
     }
+    // Older configs have no workspaces: every project is in the default one.
+    const workspaces = value.workspaces === undefined ? {} : isObj(value.workspaces) ? value.workspaces : null;
+    if (!workspaces)
+        problems.push('workspaces must be an object.');
+    for (const [name, w] of Object.entries(workspaces ?? {})) {
+        if (!WORKSPACE_NAME.test(name))
+            problems.push(`Workspace ${name} must be letters, digits, dashes and underscores.`);
+        if (!isObj(w) || typeof w.root !== 'string' || !w.root)
+            problems.push(`Workspace ${name} needs a root folder.`);
+        else {
+            if (saved?.workspaces?.[name]?.root !== w.root && !existsSync(w.root))
+                problems.push(`Workspace ${name}: ${w.root} does not exist.`);
+            if (w.context !== undefined && typeof w.context !== 'string')
+                problems.push(`Workspace ${name} context must be a file name.`);
+        }
+    }
+    problems.push(...projectProblems((projects ?? {}), (workspaces ?? {})));
     if (!Array.isArray(value.enabled) || value.enabled.some((a) => typeof a !== 'string' || !(a in AGENTS)))
         problems.push(`enabled must list agents from: ${Object.keys(AGENTS).join(', ')}.`);
     if (value.commits !== undefined && (!isObj(value.commits) || Object.entries(value.commits).some(([k, v]) => !['signOff', 'dropAiTrailers'].includes(k) || typeof v !== 'boolean')))

package/dist/runner.d.ts

@@ -16,15 +16,38 @@ type Job = {
     card: Card;
     trigger: Trigger;
     workflow: string;
+    workspace: string;
 };
 export declare function cronCard(workflow: string, task: string, at: Date): Card;
-export declare function nextJob(rc: RunContext, only?: string, workflowName?: string, opts?: {
+export interface JobQuery {
+    only?: string;
+    workflow?: string;
+    schedule?: string;
     force?: boolean;
+    busy?: Set<string>;
+    skip?: Set<string>;
+    limit?: number;
     now?: Date;
-}): Promise<Job | null>;
+}
+export declare function findJobs(rc: RunContext, q?: JobQuery): Promise<Job[]>;
+export declare function nextJob(rc: RunContext, only?: string, workflowName?: string, opts?: Omit<JobQuery, 'only' | 'workflow' | 'limit'>): Promise<Job | null>;
 export declare function cancelCard(tracker: Tracker, configDir: string, cardId: string, label: string, source?: 'linear' | 'voidtrack'): Promise<boolean>;
 export declare function tick(rc: RunContext, only?: string, opts?: {
     workflow?: string;
     from?: string;
+    schedule?: string;
+    child?: boolean;
 }): Promise<number>;
+export interface ChildRun {
+    kill(signal: NodeJS.Signals): unknown;
+    once(event: 'exit' | 'error', listener: (err?: Error) => void): unknown;
+    exitCode: number | null;
+}
+export interface DispatchDeps {
+    start: (args: string[]) => ChildRun;
+    waitMs: number;
+    reload?: () => AgentsConfig;
+}
+export declare const jobArgs: (job: Job) => string[];
+export declare function dispatch(rc: RunContext, over?: Partial<DispatchDeps>): Promise<number>;
 export {};