maestro-flow 0.5.31 → 0.5.33

package/dashboard/dist-server/src/tools/team-activity.js

@@ -0,0 +1,181 @@
+/**
+ * Human-team activity log (team-lite collaboration, Wave 2).
+ *
+ * Owns `.workflow/collab/activity.jsonl` — append-only activity bus shared
+ * across a small human team. Each entry records "who did what, when, where".
+ *
+ * Strict namespace separation: this module belongs to the HUMAN collaboration
+ * domain (`.workflow/collab/`) and must NEVER touch `.workflow/.team/` which
+ * is the agent pipeline message bus owned by `src/tools/team-msg.ts`.
+ *
+ * Hot-path contract: `reportActivity` is called from PostToolUse hooks and
+ * must NEVER throw. The underlying `appendLine` from `src/utils/jsonl-log.ts`
+ * already swallows errors; we rely on that and add best-effort wrappers.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getProjectRoot } from '../utils/path-validator.js';
+import { appendLine, tailLast, rotateIfLarge } from '../utils/jsonl-log.js';
+// Max lines read from the tail for recent-activity queries. Cap matches
+// the preflight algorithm described in docs/team-lite-design.md (section
+// "耦合 3"): 500 lines is plenty for a ±35 min window on a small team.
+const RECENT_READ_LIMIT = 500;
+// Clock tolerance (minutes): include events slightly older than the window
+// edge to account for cross-machine clock drift. Matches design doc.
+const CLOCK_TOLERANCE_MIN = 5;
+// Default rotation threshold: 10 MB.
+const DEFAULT_ROTATE_BYTES = 10 * 1024 * 1024;
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+/** Absolute path to the current activity log. */
+export function getActivityLogPath() {
+    return join(getProjectRoot(), '.workflow', 'collab', 'activity.jsonl');
+}
+/** Absolute path to the activity archive directory. */
+export function getArchiveDir() {
+    return join(getProjectRoot(), '.workflow', 'collab', 'activity-archives');
+}
+function getStateJsonPath() {
+    return join(getProjectRoot(), '.workflow', 'state.json');
+}
+// ---------------------------------------------------------------------------
+// Write path
+// ---------------------------------------------------------------------------
+/**
+ * Append an activity event to the shared log.
+ *
+ * - `ts` is auto-filled to `new Date().toISOString()` if omitted.
+ * - Silently no-ops on any error — this is called from hot paths.
+ */
+export function reportActivity(evt) {
+    try {
+        const full = {
+            ts: evt.ts ?? new Date().toISOString(),
+            user: evt.user,
+            host: evt.host,
+            action: evt.action,
+            ...(evt.phase_id !== undefined ? { phase_id: evt.phase_id } : {}),
+            ...(evt.task_id !== undefined ? { task_id: evt.task_id } : {}),
+            ...(evt.target !== undefined ? { target: evt.target } : {}),
+        };
+        appendLine(getActivityLogPath(), full);
+    }
+    catch {
+        // Hot path — never throw.
+    }
+}
+// ---------------------------------------------------------------------------
+// Read path
+// ---------------------------------------------------------------------------
+/**
+ * Return activity events from the last `windowMinutes` minutes.
+ *
+ * Algorithm (matches docs/team-lite-design.md section "耦合 3"):
+ *   1. Tail the last 500 lines of activity.jsonl.
+ *   2. Drop malformed entries (`tailLast` already does this).
+ *   3. Keep events with `ts >= now - (windowMinutes + CLOCK_TOLERANCE_MIN)`
+ *      to absorb cross-machine clock drift.
+ *
+ * Results are returned in the natural tail order (oldest -> newest), which
+ * is what `team status` wants for grouping by user.
+ */
+export function readRecentActivity(windowMinutes) {
+    if (windowMinutes <= 0)
+        return [];
+    const entries = tailLast(getActivityLogPath(), RECENT_READ_LIMIT);
+    if (entries.length === 0)
+        return [];
+    const cutoff = Date.now() - (windowMinutes + CLOCK_TOLERANCE_MIN) * 60 * 1000;
+    const out = [];
+    for (const e of entries) {
+        if (!e || typeof e.ts !== 'string')
+            continue;
+        const t = Date.parse(e.ts);
+        if (Number.isNaN(t))
+            continue;
+        if (t >= cutoff)
+            out.push(e);
+    }
+    return out;
+}
+/**
+ * Read the current workflow context from `.workflow/state.json`.
+ *
+ * Returns:
+ *   - `phase_id` from `current_phase` (if present & numeric)
+ *   - `task_id`  from `current_task_id` (if present & string)
+ *
+ * Both fields are optional. Missing state file, parse errors, or missing
+ * fields return `{}` — callers tag activity events with whatever is known.
+ *
+ * Note: `current_task_id` depends on P0.1 which may not be landed yet.
+ */
+export function readWorkflowContext() {
+    const statePath = getStateJsonPath();
+    if (!existsSync(statePath))
+        return {};
+    let raw;
+    try {
+        raw = readFileSync(statePath, 'utf-8');
+    }
+    catch {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return {};
+    const obj = parsed;
+    const out = {};
+    if (typeof obj.current_phase === 'number') {
+        out.phase_id = obj.current_phase;
+    }
+    else if (Array.isArray(obj.artifacts) && Array.isArray(obj.milestones)) {
+        // v2: derive current phase from artifact registry
+        const milestone = obj.milestones
+            .find(m => m.name === obj.current_milestone || m.id === obj.current_milestone);
+        if (milestone?.phases?.length) {
+            const arts = obj.artifacts;
+            for (const p of milestone.phases) {
+                if (arts.some(a => a.phase === p && a.milestone === obj.current_milestone && a.status === 'in_progress')) {
+                    out.phase_id = p;
+                    break;
+                }
+            }
+            if (out.phase_id == null) {
+                for (const p of milestone.phases) {
+                    if (!arts.some(a => a.type === 'execute' && a.phase === p && a.milestone === obj.current_milestone && a.status === 'completed')) {
+                        out.phase_id = p;
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    if (typeof obj.current_task_id === 'string' && obj.current_task_id) {
+        out.task_id = obj.current_task_id;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Maintenance
+// ---------------------------------------------------------------------------
+/**
+ * Rotate the activity log if it exceeds `maxBytes`.
+ *
+ * Delegates to `rotateIfLarge` in `src/utils/jsonl-log.ts`, which moves the
+ * file to `.workflow/collab/activity-archives/activity-{YYYY}W{WW}.jsonl`.
+ *
+ * Returns the archive path on success, or `null` if rotation did not run
+ * (file missing, below threshold, or I/O error).
+ */
+export function rotateIfNeeded(maxBytes = DEFAULT_ROTATE_BYTES) {
+    return rotateIfLarge(getActivityLogPath(), maxBytes, getArchiveDir());
+}
+//# sourceMappingURL=team-activity.js.map

package/dashboard/dist-server/src/tools/team-activity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"team-activity.js","sourceRoot":"","sources":["../../../../src/tools/team-activity.ts"],"names":[],"mappings":"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"}

package/dashboard/dist-server/src/tools/team-members.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Human-team member registry (team-lite collaboration, Wave 2).
+ *
+ * Owns `.workflow/collab/members/{uid}.json` — per-file member records.
+ *
+ * Strict namespace separation: this module belongs to the HUMAN collaboration
+ * domain (`.workflow/collab/`). It must NEVER touch `.workflow/.team/` which
+ * is the agent pipeline message bus owned by `src/tools/team-msg.ts`.
+ *
+ * Per-file layout is deliberate: each member writes their own JSON file so
+ * two concurrent `maestro team join` on different machines never collide on
+ * git merge (vs. a single `members.json` which cannot `merge=union`).
+ */
+export type ProjectRole = string;
+export interface MemberRecord {
+    uid: string;
+    name: string;
+    email: string;
+    host: string;
+    role: 'admin' | 'member';
+    joinedAt: string;
+    projectRoles?: ProjectRole[];
+}
+/** Absolute path to the human-collab members directory. */
+export declare function getMembersDir(): string;
+/**
+ * Resolve local git identity via `git config user.name` / `user.email`.
+ * Returns null if either is missing or git is unavailable.
+ */
+export declare function readGitIdentity(): {
+    name: string;
+    email: string;
+} | null;
+/**
+ * Derive a uid from an email address.
+ *
+ * Rule: take the local-part (before '@'), lowercase it.
+ *   "Alice@Example.COM" -> "alice"
+ *
+ * Collision handling is NOT done here — callers must check `getMembersDir`
+ * and append `-2`, `-3`, ... as needed (see `joinTeam`).
+ */
+export declare function deriveUid(email: string): string;
+/** Return the machine hostname. Exported so tests can stub if needed. */
+export declare function getHost(): string;
+/**
+ * List all known members. Returns an empty array if the directory does not
+ * exist yet. Files that fail to parse as `MemberRecord` JSON are skipped
+ * silently — corrupt files should not break `whoami` / `status`.
+ */
+export declare function listMembers(): MemberRecord[];
+/** Read a single member by uid, or null if the file does not exist. */
+export declare function getMemberByUid(uid: string): MemberRecord | null;
+/**
+ * Return the member record matching the current git identity.
+ *
+ * Matching uses `email` (case-insensitive), NOT just `uid`, so two users who
+ * happened to get the same local-part on different domains still resolve to
+ * their own record.
+ *
+ * Returns null if git identity is unavailable or no record matches.
+ */
+export declare function resolveSelf(): MemberRecord | null;
+/**
+ * Assert that team mode is active (i.e. the current git user has a member
+ * record). Throws a descriptive error if `resolveSelf()` returns null.
+ *
+ * Returns the resolved `MemberRecord` for convenience so callers can chain:
+ *   const self = requireTeamMode();
+ */
+export declare function requireTeamMode(): MemberRecord;
+/**
+ * Assert the current user holds the given role. Calls `resolveSelf()`
+ * internally, so it also fails when team mode is off.
+ *
+ * Throws with a message like:
+ *   "This operation requires admin role. Your role: member"
+ */
+export declare function requireRole(required: 'admin' | 'member'): MemberRecord;
+/**
+ * Join the team. Idempotent.
+ *
+ * Flow:
+ *   1. Read git identity (throws if name/email missing — cannot join without it).
+ *   2. If a record with the same email already exists, return it unchanged
+ *      (preserves `joinedAt` and any prior `role`).
+ *   3. Derive uid from email local-part. If another member with a different
+ *      email already owns that uid, append `-2`, `-3`, ... until free.
+ *   4. Assign role: explicit `opts.role` wins; otherwise the very first member
+ *      to join becomes `admin`, everyone after is `member`.
+ *   5. Write `.workflow/collab/members/{uid}.json` atomically via `writeFileSync`.
+ */
+export declare function joinTeam(opts?: {
+    role?: 'admin' | 'member';
+}): MemberRecord;
+/**
+ * Add a project role to a member's record. Idempotent — adding a role that
+ * already exists is a no-op. Returns the updated record, or null if the
+ * member was not found.
+ */
+export declare function addProjectRole(uid: string, role: string): MemberRecord | null;
+/**
+ * Remove a project role from a member's record. No-op if the role is not
+ * present. Returns the updated record, or null if the member was not found.
+ */
+export declare function removeProjectRole(uid: string, role: string): MemberRecord | null;
+/**
+ * List project roles. When `uid` is provided, returns that member's roles
+ * (or an empty array). When omitted, returns a Map of all members' roles.
+ */
+export declare function listProjectRoles(uid?: string): ProjectRole[] | Map<string, ProjectRole[]>;

package/dashboard/dist-server/src/tools/team-members.js

@@ -0,0 +1,303 @@
+/**
+ * Human-team member registry (team-lite collaboration, Wave 2).
+ *
+ * Owns `.workflow/collab/members/{uid}.json` — per-file member records.
+ *
+ * Strict namespace separation: this module belongs to the HUMAN collaboration
+ * domain (`.workflow/collab/`). It must NEVER touch `.workflow/.team/` which
+ * is the agent pipeline message bus owned by `src/tools/team-msg.ts`.
+ *
+ * Per-file layout is deliberate: each member writes their own JSON file so
+ * two concurrent `maestro team join` on different machines never collide on
+ * git merge (vs. a single `members.json` which cannot `merge=union`).
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { hostname } from 'node:os';
+import { execSync } from 'node:child_process';
+import { getProjectRoot } from '../utils/path-validator.js';
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+/** Absolute path to the human-collab members directory. */
+export function getMembersDir() {
+    return join(getProjectRoot(), '.workflow', 'collab', 'members');
+}
+function getMemberFilePath(uid) {
+    return join(getMembersDir(), `${uid}.json`);
+}
+// ---------------------------------------------------------------------------
+// Identity helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve local git identity via `git config user.name` / `user.email`.
+ * Returns null if either is missing or git is unavailable.
+ */
+export function readGitIdentity() {
+    const name = tryGitConfig('user.name');
+    const email = tryGitConfig('user.email');
+    if (!name || !email)
+        return null;
+    return { name, email };
+}
+function tryGitConfig(key) {
+    try {
+        const out = execSync(`git config ${key}`, {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Derive a uid from an email address.
+ *
+ * Rule: take the local-part (before '@'), lowercase it.
+ *   "Alice@Example.COM" -> "alice"
+ *
+ * Collision handling is NOT done here — callers must check `getMembersDir`
+ * and append `-2`, `-3`, ... as needed (see `joinTeam`).
+ */
+export function deriveUid(email) {
+    const at = email.indexOf('@');
+    const local = at >= 0 ? email.slice(0, at) : email;
+    return local.trim().toLowerCase();
+}
+/** Return the machine hostname. Exported so tests can stub if needed. */
+export function getHost() {
+    return hostname();
+}
+// ---------------------------------------------------------------------------
+// Reads
+// ---------------------------------------------------------------------------
+/**
+ * List all known members. Returns an empty array if the directory does not
+ * exist yet. Files that fail to parse as `MemberRecord` JSON are skipped
+ * silently — corrupt files should not break `whoami` / `status`.
+ */
+export function listMembers() {
+    const dir = getMembersDir();
+    if (!existsSync(dir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.endsWith('.json'))
+            continue;
+        const rec = readMemberFile(join(dir, entry));
+        if (rec)
+            out.push(rec);
+    }
+    return out;
+}
+/** Read a single member by uid, or null if the file does not exist. */
+export function getMemberByUid(uid) {
+    const path = getMemberFilePath(uid);
+    if (!existsSync(path))
+        return null;
+    return readMemberFile(path);
+}
+/**
+ * Return the member record matching the current git identity.
+ *
+ * Matching uses `email` (case-insensitive), NOT just `uid`, so two users who
+ * happened to get the same local-part on different domains still resolve to
+ * their own record.
+ *
+ * Returns null if git identity is unavailable or no record matches.
+ */
+export function resolveSelf() {
+    const ident = readGitIdentity();
+    if (!ident)
+        return null;
+    const target = ident.email.toLowerCase();
+    for (const m of listMembers()) {
+        if (m.email.toLowerCase() === target)
+            return m;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Guards
+// ---------------------------------------------------------------------------
+/**
+ * Assert that team mode is active (i.e. the current git user has a member
+ * record). Throws a descriptive error if `resolveSelf()` returns null.
+ *
+ * Returns the resolved `MemberRecord` for convenience so callers can chain:
+ *   const self = requireTeamMode();
+ */
+export function requireTeamMode() {
+    const self = resolveSelf();
+    if (!self) {
+        throw new Error("Team mode not enabled. Run 'maestro team join' first.");
+    }
+    return self;
+}
+/**
+ * Assert the current user holds the given role. Calls `resolveSelf()`
+ * internally, so it also fails when team mode is off.
+ *
+ * Throws with a message like:
+ *   "This operation requires admin role. Your role: member"
+ */
+export function requireRole(required) {
+    const self = requireTeamMode();
+    if (self.role !== required) {
+        throw new Error(`This operation requires ${required} role. Your role: ${self.role}`);
+    }
+    return self;
+}
+// ---------------------------------------------------------------------------
+// Writes
+// ---------------------------------------------------------------------------
+/**
+ * Join the team. Idempotent.
+ *
+ * Flow:
+ *   1. Read git identity (throws if name/email missing — cannot join without it).
+ *   2. If a record with the same email already exists, return it unchanged
+ *      (preserves `joinedAt` and any prior `role`).
+ *   3. Derive uid from email local-part. If another member with a different
+ *      email already owns that uid, append `-2`, `-3`, ... until free.
+ *   4. Assign role: explicit `opts.role` wins; otherwise the very first member
+ *      to join becomes `admin`, everyone after is `member`.
+ *   5. Write `.workflow/collab/members/{uid}.json` atomically via `writeFileSync`.
+ */
+export function joinTeam(opts) {
+    const ident = readGitIdentity();
+    if (!ident) {
+        throw new Error('Git identity not configured. Run `git config user.name "Your Name"` and ' +
+            '`git config user.email "you@example.com"` before joining.');
+    }
+    // Idempotency: same email already registered -> return existing record.
+    const existing = resolveSelf();
+    if (existing)
+        return existing;
+    const dir = getMembersDir();
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const base = deriveUid(ident.email);
+    const uid = allocateUid(base, ident.email);
+    // Role: explicit wins. Otherwise first-joiner is admin.
+    const role = opts?.role ?? (listMembers().length === 0 ? 'admin' : 'member');
+    const record = {
+        uid,
+        name: ident.name,
+        email: ident.email,
+        host: getHost(),
+        role,
+        joinedAt: new Date().toISOString(),
+    };
+    writeFileSync(getMemberFilePath(uid), JSON.stringify(record, null, 2), 'utf-8');
+    return record;
+}
+// ---------------------------------------------------------------------------
+// Project roles
+// ---------------------------------------------------------------------------
+/**
+ * Add a project role to a member's record. Idempotent — adding a role that
+ * already exists is a no-op. Returns the updated record, or null if the
+ * member was not found.
+ */
+export function addProjectRole(uid, role) {
+    const member = getMemberByUid(uid);
+    if (!member)
+        return null;
+    const roles = member.projectRoles ?? [];
+    if (roles.includes(role))
+        return member; // already present
+    member.projectRoles = [...roles, role];
+    writeFileSync(getMemberFilePath(uid), JSON.stringify(member, null, 2), 'utf-8');
+    return member;
+}
+/**
+ * Remove a project role from a member's record. No-op if the role is not
+ * present. Returns the updated record, or null if the member was not found.
+ */
+export function removeProjectRole(uid, role) {
+    const member = getMemberByUid(uid);
+    if (!member)
+        return null;
+    const roles = member.projectRoles ?? [];
+    const filtered = roles.filter((r) => r !== role);
+    if (filtered.length === roles.length)
+        return member; // role was not present
+    member.projectRoles = filtered.length > 0 ? filtered : undefined;
+    writeFileSync(getMemberFilePath(uid), JSON.stringify(member, null, 2), 'utf-8');
+    return member;
+}
+/**
+ * List project roles. When `uid` is provided, returns that member's roles
+ * (or an empty array). When omitted, returns a Map of all members' roles.
+ */
+export function listProjectRoles(uid) {
+    if (uid !== undefined) {
+        const member = getMemberByUid(uid);
+        return member?.projectRoles ?? [];
+    }
+    const map = new Map();
+    for (const m of listMembers()) {
+        map.set(m.uid, m.projectRoles ?? []);
+    }
+    return map;
+}
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+function readMemberFile(path) {
+    try {
+        const raw = readFileSync(path, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.uid === 'string' &&
+            typeof parsed.name === 'string' &&
+            typeof parsed.email === 'string' &&
+            typeof parsed.host === 'string' &&
+            (parsed.role === 'admin' || parsed.role === 'member') &&
+            typeof parsed.joinedAt === 'string') {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Allocate a free uid derived from `base`.
+ *
+ * - If `{base}.json` does not exist, use it.
+ * - If `{base}.json` exists AND belongs to the same email, reuse it
+ *   (this path is normally caught earlier by `resolveSelf`, but we keep
+ *   the safety net in case files got out of sync).
+ * - Otherwise try `{base}-2`, `{base}-3`, ... until a free slot is found.
+ */
+function allocateUid(base, email) {
+    const ownEmail = email.toLowerCase();
+    const firstPath = getMemberFilePath(base);
+    if (!existsSync(firstPath))
+        return base;
+    const existing = readMemberFile(firstPath);
+    if (existing && existing.email.toLowerCase() === ownEmail)
+        return base;
+    for (let n = 2; n < 1000; n++) {
+        const candidate = `${base}-${n}`;
+        const candidatePath = getMemberFilePath(candidate);
+        if (!existsSync(candidatePath))
+            return candidate;
+        const rec = readMemberFile(candidatePath);
+        if (rec && rec.email.toLowerCase() === ownEmail)
+            return candidate;
+    }
+    throw new Error(`Could not allocate uid for email ${email} after 1000 attempts`);
+}
+//# sourceMappingURL=team-members.js.map

package/dashboard/dist-server/src/tools/team-members.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"team-members.js","sourceRoot":"","sources":["../../../../src/tools/team-members.ts"],"names":[],"mappings":"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"}

package/dashboard/dist-server/src/utils/cooldown-guard.d.ts

@@ -0,0 +1,16 @@
+export interface CooldownGuardOptions {
+    prefix: string;
+    cooldownMs: number;
+}
+export declare class CooldownGuard {
+    private readonly prefix;
+    private readonly cooldownMs;
+    constructor(opts: CooldownGuardOptions);
+    shouldRun(sessionId: string): boolean;
+    markDone(sessionId: string, extra?: Record<string, unknown>): void;
+    timeSinceLastMs(sessionId: string): number | null;
+    private read;
+    private path;
+}
+export declare const kgSyncGuard: CooldownGuard;
+export declare const kgInitGuard: CooldownGuard;