team 0.0.1 → 0.1.1

package/dist/file/lines.js

@@ -0,0 +1,277 @@
+// Edits the team file by the line. Comments, order and every other seat stay as written.
+// Nothing here re-serialises the file.
+function indent(line) {
+    let n = 0;
+    while (line[n] === ' ')
+        n++;
+    return n;
+}
+function scalar(raw) {
+    const value = raw.replace(/\s+#.*$/, '').trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function field(lines, name) {
+    for (const line of lines) {
+        const match = new RegExp(`^\\s*${name}:\\s*(.*)$`).exec(line);
+        if (!match)
+            continue;
+        return scalar(match[1] ?? '');
+    }
+    return null;
+}
+/** A seat's name, including one written on the entry's first line: `- name: helper`. */
+function seatName(body) {
+    const inline = /^\s*-\s+name:\s*(.*)$/.exec(body[0] ?? '');
+    if (inline)
+        return scalar(inline[1] ?? '');
+    return field(body, 'name');
+}
+/** The seat entries under `seats:`, in order. A file with no seats section has none. */
+export function seatBlocks(text) {
+    const lines = text.split('\n');
+    const header = lines.findIndex((line) => /^seats:\s*(#.*)?$/.test(line));
+    if (header < 0)
+        return [];
+    const key = indent(lines[header] ?? '');
+    const blocks = [];
+    let start = -1;
+    const flush = (end) => {
+        if (start < 0)
+            return;
+        const body = lines.slice(start, end);
+        const count = Number(field(body, 'count') ?? '1');
+        blocks.push({ start, end, name: seatName(body), count: Number.isInteger(count) && count > 0 ? count : 1 });
+        start = -1;
+    };
+    for (let i = header + 1; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (line.trim() === '' || /^\s*#/.test(line))
+            continue;
+        if (indent(line) <= key) {
+            flush(i);
+            break;
+        }
+        if (/^\s*-\s+/.test(line)) {
+            flush(i);
+            start = i;
+        }
+    }
+    if (start >= 0)
+        flush(lines.length);
+    return blocks;
+}
+function expanded(block) {
+    if (!block.name)
+        return [];
+    const names = [block.name];
+    for (let instance = 2; instance <= block.count; instance++)
+        names.push(`${block.name}-${instance}`);
+    return names;
+}
+/** Whether `name` is a seat entry, including one that `count` expands to. */
+export function hasSeat(text, name) {
+    return seatBlocks(text).some((block) => expanded(block).includes(name));
+}
+function replaceLines(text, start, end, insert) {
+    const lines = text.split('\n');
+    lines.splice(start, end - start, ...insert);
+    return lines.join('\n');
+}
+function body(text, block) {
+    return text.split('\n').slice(block.start, block.end);
+}
+function setValue(line, value) {
+    const match = /^(\s*(?:-\s+)?[A-Za-z0-9_-]+:\s*)(.*)$/.exec(line);
+    if (!match)
+        return line;
+    const rest = match[2] ?? '';
+    const comment = /\s+#.*$/.exec(rest)?.[0] ?? '';
+    const raw = rest.slice(0, rest.length - comment.length).trim();
+    const quoted = raw.startsWith('"') ? `"${value}"` : raw.startsWith("'") ? `'${value}'` : value;
+    return `${match[1]}${quoted}${comment}`;
+}
+/** One `count` entry becomes one explicit seat per instance. Other lines are copied, not rebuilt. */
+export function rewriteCount(text, declared) {
+    const block = seatBlocks(text).find((item) => item.name === declared && item.count > 1);
+    if (!block)
+        return null;
+    const lines = body(text, block);
+    const label = field(lines, 'label');
+    const copies = [];
+    for (let instance = 1; instance <= block.count; instance++) {
+        const suffix = instance === 1 ? '' : `-${instance}`;
+        copies.push(...lines.flatMap((line) => {
+            if (/^\s*count:/.test(line))
+                return [];
+            if (instance === 1)
+                return [line];
+            if (/^\s*(?:-\s+)?name:/.test(line))
+                return [setValue(line, `${declared}${suffix}`)];
+            if (label !== null && /^\s*label:/.test(line))
+                return [setValue(line, `${label}${suffix}`)];
+            return [line];
+        }));
+    }
+    return replaceLines(text, block.start, block.end, copies);
+}
+/** True when this seat's own entry, or the count entry it comes from, says stopped. */
+export function seatIsStopped(text, name) {
+    const lines = text.split('\n');
+    const exact = seatBlocks(text).find((block) => block.name === name);
+    const block = exact ?? seatBlocks(text).find((item) => expanded(item).includes(name));
+    if (!block)
+        return false;
+    return lines.slice(block.start, block.end).some((line) => /^\s*stopped:\s*(true|yes)\b/.test(line));
+}
+/** Drops `stopped: true` from the entry whose name is `name`. A counted entry is split first. */
+export function clearStopped(text, name) {
+    const counted = seatBlocks(text).find((block) => block.count > 1 && expanded(block).includes(name));
+    const rewritten = counted?.name ? rewriteCount(text, counted.name) ?? text : text;
+    const block = seatBlocks(rewritten).find((item) => item.name === name);
+    if (!block)
+        return rewritten;
+    const lines = body(rewritten, block).filter((line) => !/^\s*stopped:\s*(true|yes)\s*(#.*)?$/.test(line));
+    return replaceLines(rewritten, block.start, block.end, lines);
+}
+function prepared(text, name) {
+    const counted = seatBlocks(text).find((block) => block.count > 1 && expanded(block).includes(name));
+    const rewritten = counted?.name ? rewriteCount(text, counted.name) ?? text : text;
+    const block = seatBlocks(rewritten).find((item) => item.name === name);
+    return block ? { text: rewritten, block } : null;
+}
+/** Drops trailing comments and blank lines back into the file, ahead of the next entry. */
+function fieldEnd(lines) {
+    let end = lines.length;
+    while (end > 0) {
+        const line = lines[end - 1] ?? '';
+        if (line.trim() !== '' && !/^\s*#/.test(line))
+            break;
+        end--;
+    }
+    return end;
+}
+/** Takes `name` out of the file. A counted entry is split first, so the other instances stay. */
+export function takeOut(text, name) {
+    const ready = prepared(text, name);
+    if (!ready)
+        return text;
+    const lines = body(ready.text, ready.block);
+    return replaceLines(ready.text, ready.block.start, ready.block.start + fieldEnd(lines), []);
+}
+/** Leaves `name` in the file with `stopped: true`. A counted entry is split first. */
+export function markStopped(text, name) {
+    const ready = prepared(text, name);
+    if (!ready)
+        return text;
+    const lines = body(ready.text, ready.block);
+    if (lines.some((line) => /^\s*stopped:\s*(true|yes)\b/.test(line)))
+        return ready.text;
+    const nested = lines.find((line) => /^\s+[A-Za-z0-9_-]+:/.test(line));
+    const pad = ' '.repeat(nested ? indent(nested) : indent(lines[0] ?? '') + 2);
+    lines.splice(fieldEnd(lines), 0, `${pad}stopped: true`);
+    return replaceLines(ready.text, ready.block.start, ready.block.end, lines);
+}
+/**
+ * Puts `name`'s entry back from `approved` when the current text lacks it.
+ * The entry is inserted after whichever approved neighbour is still present.
+ */
+export function restoreSeat(current, approved, name) {
+    if (hasSeat(current, name))
+        return current;
+    const approvedBlocks = seatBlocks(approved);
+    const at = approvedBlocks.findIndex((block) => expanded(block).includes(name));
+    const source = approvedBlocks[at];
+    if (!source || at < 0)
+        return current;
+    const inserting = instanceLines(approved, source, name);
+    if (!inserting)
+        return current;
+    const lines = current.split('\n');
+    const header = lines.findIndex((line) => /^seats:\s*(#.*)?$/.test(line));
+    if (header < 0)
+        return current;
+    const currentBlocks = seatBlocks(current);
+    let insertAt = header + 1;
+    let placed = false;
+    const among = siblingSlot(currentBlocks, source, name);
+    if (among !== null) {
+        insertAt = among;
+        placed = true;
+    }
+    for (let i = at - 1; i >= 0 && !placed; i--) {
+        const neighbour = approvedBlocks[i];
+        const found = neighbour ? currentBlocks.find((block) => block.name === neighbour.name) : undefined;
+        if (found) {
+            insertAt = found.end;
+            placed = true;
+        }
+    }
+    for (let i = at + 1; i < approvedBlocks.length && !placed; i++) {
+        const neighbour = approvedBlocks[i];
+        const found = neighbour ? currentBlocks.find((block) => block.name === neighbour.name) : undefined;
+        if (found) {
+            insertAt = found.start;
+            placed = true;
+        }
+    }
+    if (!placed && currentBlocks.length > 0) {
+        const last = currentBlocks[currentBlocks.length - 1];
+        if (last)
+            insertAt = last.end;
+    }
+    lines.splice(insertAt, 0, ...inserting);
+    return lines.join('\n');
+}
+/** Where a restored instance sits among the copies of the same count entry that are still in the file. */
+function siblingSlot(currentBlocks, source, name) {
+    if (source.count <= 1 || !source.name)
+        return null;
+    const mine = instanceNumber(source.name, name);
+    if (mine === null)
+        return null;
+    let lower = null;
+    let lowerN = 0;
+    let higher = null;
+    let higherN = Number.POSITIVE_INFINITY;
+    for (const block of currentBlocks) {
+        if (!block.name || !expanded(source).includes(block.name))
+            continue;
+        const n = instanceNumber(source.name, block.name);
+        if (n === null)
+            continue;
+        if (n < mine && n > lowerN) {
+            lower = block;
+            lowerN = n;
+        }
+        else if (n > mine && n < higherN) {
+            higher = block;
+            higherN = n;
+        }
+    }
+    if (lower)
+        return lower.end;
+    return higher ? higher.start : null;
+}
+function instanceNumber(declared, name) {
+    if (name === declared)
+        return 1;
+    const prefix = `${declared}-`;
+    if (!name.startsWith(prefix))
+        return null;
+    const rest = name.slice(prefix.length);
+    return /^\d+$/.test(rest) ? Number(rest) : null;
+}
+// A counted approved entry is one block for every instance. Restoring one of them inserts that
+// instance alone; copying the whole `count` entry would repeat the declared name.
+function instanceLines(approved, source, name) {
+    if (source.count <= 1 || !source.name)
+        return body(approved, source);
+    const rewritten = rewriteCount(approved, source.name);
+    if (!rewritten)
+        return null;
+    const instance = seatBlocks(rewritten).find((block) => block.name === name);
+    return instance ? body(rewritten, instance) : null;
+}

package/dist/file/load.d.ts

@@ -0,0 +1,7 @@
+import type { LoadResult, Problem, TeamFile } from './types.ts';
+export declare const TEAM_FILE = ".agents/team.yaml";
+export declare function findRoot(cwd: string): string | null;
+export declare function loadTeamFile(cwd: string, options?: {
+    file?: string;
+}): LoadResult;
+export declare function placedProblems(team: TeamFile, root: string): Problem[];

package/dist/file/load.js

@@ -0,0 +1,90 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { fixedFolder } from "./paths.js";
+import { validateTeamFile } from "./validate.js";
+export const TEAM_FILE = '.agents/team.yaml';
+// The project's root: the main checkout, found through git's common directory, so a command run
+// in a subfolder or in a linked worktree reads the same `.agents/`.
+export function findRoot(cwd) {
+    try {
+        const common = execFileSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return common ? dirname(common) : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Finds, reads and validates the team file. With `file`, the root is the folder that holds the
+// file's `.agents/`, or the file's own folder when it sits elsewhere.
+export function loadTeamFile(cwd, options = {}) {
+    let path;
+    let root;
+    if (options.file) {
+        path = isAbsolute(options.file) ? options.file : resolve(cwd, options.file);
+        const folder = dirname(path);
+        root = folder.endsWith('.agents') ? dirname(folder) : folder;
+    }
+    else {
+        const found = findRoot(cwd);
+        if (!found)
+            return { ok: false, errors: [{ line: 0, message: 'not inside a git repository: run team from a project, or pass --file' }] };
+        root = found;
+        path = join(root, TEAM_FILE);
+    }
+    if (!existsSync(path)) {
+        return {
+            ok: false,
+            path,
+            errors: [{
+                    line: 0,
+                    message: options.file
+                        ? `no team file at ${options.file}`
+                        : 'no team file here; it is private to each clone: run `team init`, or `team init --restore` to bring back the copy you last approved on this machine',
+                }],
+        };
+    }
+    // One read. Callers that store the text (approve) use this string, the one that was validated.
+    const text = readFileSync(path, 'utf8');
+    const result = validateTeamFile(text);
+    if (!result.ok)
+        return { ...result, path };
+    const errors = placedProblems(result.team, root);
+    return errors.length ? { ok: false, errors, path } : { ...result, root, path, text };
+}
+function real(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+// What only shows once the root is known: a folder named by its own name can still be the
+// project's parent, as "../../Code/*" is for a project at ~/Code/acme. Validation on the text
+// alone can't see that; here every fixed folder is resolved, symlinks included.
+export function placedProblems(team, root) {
+    const project = real(root);
+    const problems = [];
+    const holdsProject = (folder) => {
+        const full = real(resolve(project, folder));
+        return full !== project && project.startsWith(full.endsWith(sep) ? full : full + sep);
+    };
+    for (const pattern of team.trust) {
+        if (holdsProject(fixedFolder(pattern))) {
+            problems.push({ line: 0, message: `trust: "${pattern}" names the project's parent or a folder above it: it would trust every folder beside the project` });
+        }
+    }
+    const path = team.workspace.path;
+    if (path) {
+        const folder = path.split('/').slice(0, -1).join('/').replaceAll('{repo}', team.project) || '.';
+        if (holdsProject(folder)) {
+            problems.push({ line: 0, message: `workspace.path: "${path}" puts worktrees in the project's parent or a folder above it: give them a folder of their own` });
+        }
+    }
+    return problems;
+}

package/dist/file/paths.d.ts

@@ -0,0 +1,6 @@
+export declare function normalize(path: string): string;
+export declare function insideProject(path: string): boolean;
+export declare function trustProblem(pattern: string): string | null;
+export declare function fixedFolder(pattern: string): string;
+export declare function protectedBy(path: string, checkouts: readonly string[]): string | null;
+export declare function insideTrust(path: string, patterns: string[]): boolean;

package/dist/file/paths.js

@@ -0,0 +1,77 @@
+// Paths in a team file are relative to the project's root, with "/" between segments. These
+// checks are on the text alone; symlinks are resolved when trust is applied.
+export function normalize(path) {
+    const out = [];
+    for (const segment of path.split('/')) {
+        if (!segment || segment === '.')
+            continue;
+        if (segment === '..' && out.length && out[out.length - 1] !== '..')
+            out.pop();
+        else
+            out.push(segment);
+    }
+    return out.join('/') || '.';
+}
+export function insideProject(path) {
+    const normal = normalize(path);
+    return normal !== '..' && !normal.startsWith('../');
+}
+// Why a trust pattern is refused, or null. A pattern is a folder inside the project, or one under
+// a fixed folder that is neither the project's parent nor an ancestor; "*" matches one segment
+// and only as the last one.
+export function trustProblem(pattern) {
+    if (pattern.startsWith('/') || pattern.startsWith('~') || /^[A-Za-z]:[\\/]/.test(pattern)) {
+        return 'must be relative to the project';
+    }
+    const segments = normalize(pattern).split('/');
+    const last = segments.length - 1;
+    for (let i = 0; i < segments.length; i++) {
+        const segment = segments[i];
+        if (segment.includes('*') && (segment !== '*' || i !== last))
+            return 'takes "*" only as a whole last segment';
+    }
+    const fixed = segments[last] === '*' ? segments.slice(0, last) : segments;
+    if (fixed.length && fixed.every((segment) => segment === '..')) {
+        return segments[last] === '*'
+            ? 'would trust every folder beside the project or above it: name a fixed folder before "*"'
+            : 'is a parent of the project: trust a folder of the team\'s own';
+    }
+    return null;
+}
+// The folder a pattern keeps fixed: the pattern without its trailing "*".
+export function fixedFolder(pattern) {
+    const segments = normalize(pattern).split('/');
+    if (segments[segments.length - 1] === '*')
+        segments.pop();
+    return segments.join('/') || '.';
+}
+// The protected checkout `path` is in, or null. A checkout named "." is the project root, so every
+// path inside the project is inside it; every other entry names that folder and what lies under it.
+export function protectedBy(path, checkouts) {
+    const target = normalize(path);
+    for (const checkout of checkouts) {
+        const folder = normalize(checkout);
+        if (folder === '.') {
+            if (insideProject(target))
+                return checkout;
+            continue;
+        }
+        if (target === folder || target.startsWith(`${folder}/`))
+            return checkout;
+    }
+    return null;
+}
+// True when `path` is a trusted folder or lies under one.
+export function insideTrust(path, patterns) {
+    const target = normalize(path).split('/');
+    return patterns.some((pattern) => {
+        if (trustProblem(pattern))
+            return false;
+        const segments = normalize(pattern).split('/');
+        if (segments.length === 1 && segments[0] === '.')
+            return insideProject(path);
+        if (target.length < segments.length)
+            return false;
+        return segments.every((segment, i) => segment === '*' || segment === target[i]);
+    });
+}

package/dist/file/secrets.d.ts

@@ -0,0 +1,6 @@
+import type { YamlNode } from '../yaml.ts';
+import type { Problem } from './types.ts';
+export declare function findSecrets(root: YamlNode): {
+    refused: Problem[];
+    warned: Problem[];
+};

package/dist/file/secrets.js

@@ -0,0 +1,54 @@
+// A team file never holds a credential. A value with a known key prefix, a private key or a URL
+// with credentials refuses the file. A long random-looking string only warns: channel ids and
+// slugs look like one.
+const KEY_PREFIXES = [
+    'sk-', 'ghp_', 'gho_', 'ghu_', 'ghs_', 'ghr_', 'github_pat_', 'glpat-', 'xoxb-', 'xoxp-', 'xoxa-', 'xoxs-',
+    'AKIA', 'ASIA', 'AIza', 'lin_api_', 'npm_', 'shpat_', 'dckr_pat_',
+];
+export function findSecrets(root) {
+    const refused = [];
+    const warned = [];
+    walk(root, (value, line) => {
+        for (const word of value.split(/[\s"'=,;]+/)) {
+            if (KEY_PREFIXES.some((prefix) => word.startsWith(prefix) && word.length >= prefix.length + 16)) {
+                refused.push({ line, message: 'a value shaped like a key or token: a team file never holds a credential' });
+                return;
+            }
+        }
+        if (/-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(value)) {
+            refused.push({ line, message: 'a private key: a team file never holds a credential' });
+        }
+        else if (/[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/@]+@/i.test(value)) {
+            refused.push({ line, message: 'a URL with credentials: a team file never holds a credential' });
+        }
+        else if (value.split(/\s+/).some(looksRandom)) {
+            warned.push({ line, message: 'a long random-looking value: check it is not a credential' });
+        }
+    });
+    return { refused, warned };
+}
+function walk(node, visit) {
+    if (node.kind === 'scalar') {
+        if (typeof node.value === 'string')
+            visit(node.value, node.line);
+    }
+    else if (node.kind === 'seq') {
+        for (const item of node.items)
+            walk(item, visit);
+    }
+    else {
+        for (const entry of node.entries)
+            walk(entry.value, visit);
+    }
+}
+function looksRandom(word) {
+    if (word.length < 32 || !/^[A-Za-z0-9+/_=-]+$/.test(word))
+        return false;
+    const counts = new Map();
+    for (const c of word)
+        counts.set(c, (counts.get(c) ?? 0) + 1);
+    let entropy = 0;
+    for (const count of counts.values())
+        entropy -= (count / word.length) * Math.log2(count / word.length);
+    return entropy > 4;
+}

package/dist/file/signature.d.ts

@@ -0,0 +1,13 @@
+export declare const DEFAULT_COMMIT_TEMPLATE = "Agent: {display} \u00B7 {role}";
+export declare const DEFAULT_PR_TEMPLATE = "**Agent:** {display} \u00B7 {role}";
+export declare const DEFAULT_FORBIDDEN: string[];
+export type Signer = {
+    display: string;
+    model: string;
+    version: string;
+    role: string;
+};
+export declare function renderSignature(template: string, seat: Signer): string;
+export declare function templateProblem(template: string): string | null;
+export declare function isTrailerTemplate(template: string): boolean;
+export declare function hasVersionToken(display: string, version: string): boolean;

package/dist/file/signature.js

@@ -0,0 +1,36 @@
+export const DEFAULT_COMMIT_TEMPLATE = 'Agent: {display} · {role}';
+export const DEFAULT_PR_TEMPLATE = '**Agent:** {display} · {role}';
+// Added to every file's `identity.forbidden`, never replaced by it.
+export const DEFAULT_FORBIDDEN = ['^Claude-Session:', 'https?://claude\\.ai/code/session'];
+export function renderSignature(template, seat) {
+    return template.replace(/\{(display|model|version|role)\}/g, (_, name) => seat[name]);
+}
+// What a template must hold to name a model, its version and a role.
+export function templateProblem(template) {
+    if (!template.includes('{role}'))
+        return 'the template must contain {role}';
+    if (!template.includes('{display}') && !(template.includes('{model}') && template.includes('{version}'))) {
+        return 'the template must contain {display}, or both {model} and {version}';
+    }
+    const unknown = template.match(/\{[^}]*\}/g)?.find((p) => !/^\{(display|model|version|role)\}$/.test(p));
+    return unknown ? `unknown placeholder ${unknown}` : null;
+}
+// git reads a line as a trailer only when it is "<token>: <value>", the token without spaces.
+export function isTrailerTemplate(template) {
+    const line = renderSignature(template, { display: 'Model 1', model: 'Model', version: '1', role: 'role' });
+    return /^[A-Za-z0-9-]+: \S/.test(line);
+}
+// The version as a token of the display: no letter, digit or dot directly before or after it.
+export function hasVersionToken(display, version) {
+    let from = 0;
+    for (;;) {
+        const at = display.indexOf(version, from);
+        if (at < 0)
+            return false;
+        const before = display[at - 1] ?? '';
+        const after = display[at + version.length] ?? '';
+        if (!/[\p{L}\p{N}.]/u.test(before) && !/[\p{L}\p{N}.]/u.test(after))
+            return true;
+        from = at + 1;
+    }
+}