@aopslabs/aops 0.2.0

package/dist/utils/project-context.js

@@ -0,0 +1,255 @@
+import { normalizeNonEmpty, } from './command.js';
+import { loadAopsRepoConfig, } from './repo-config.js';
+function normalizeProjectName(value) {
+    return normalizeNonEmpty(value)?.toLowerCase();
+}
+function normalizeProjectSlug(value) {
+    return normalizeNonEmpty(value)?.toLowerCase();
+}
+function matchProjectByName(project, projectName) {
+    return normalizeProjectName(project.name) === normalizeProjectName(projectName);
+}
+function matchProjectBySlug(project, projectSlug) {
+    return normalizeProjectSlug(project.slug) === normalizeProjectSlug(projectSlug);
+}
+function resolveProjectFromConfig(projects, options) {
+    const explicitProjectName = normalizeNonEmpty(options.projectName);
+    if (explicitProjectName) {
+        const matches = projects.filter((project) => matchProjectByName(project, explicitProjectName));
+        if (matches.length === 0) {
+            const available = projects.map((project) => project.name).join(', ');
+            throw new Error(`Project "${explicitProjectName}" was not found in repo config. Available projects: ${available || '(none)'}.`);
+        }
+        if (matches.length > 1) {
+            const ids = matches
+                .map((project) => `${project.name} (${project.scopeId ?? project.projectId})`)
+                .join(', ');
+            throw new Error(`Project name "${explicitProjectName}" is ambiguous in repo config: ${ids}.`);
+        }
+        return matches[0];
+    }
+    const explicitProjectSlug = normalizeNonEmpty(options.projectSlug);
+    if (explicitProjectSlug) {
+        const matches = projects.filter((project) => matchProjectBySlug(project, explicitProjectSlug));
+        if (matches.length === 0) {
+            const available = projects
+                .map((project) => normalizeNonEmpty(project.slug))
+                .filter((entry) => Boolean(entry))
+                .join(', ');
+            throw new Error(`Project slug "${explicitProjectSlug}" was not found in repo config. Available slugs: ${available || '(none)'}.`);
+        }
+        if (matches.length > 1) {
+            const ids = matches
+                .map((project) => `${project.slug ?? project.name} (${project.scopeId ?? project.projectId})`)
+                .join(', ');
+            throw new Error(`Project slug "${explicitProjectSlug}" is ambiguous in repo config: ${ids}.`);
+        }
+        return matches[0];
+    }
+    const explicitScopeId = normalizeNonEmpty(options.scopeId);
+    if (explicitScopeId) {
+        return (projects.find((project) => project.scopeId === explicitScopeId) ??
+            projects.find((project) => project.projectId === explicitScopeId) ??
+            null);
+    }
+    const explicitProjectId = normalizeNonEmpty(options.projectId);
+    if (explicitProjectId) {
+        return (projects.find((project) => project.projectId === explicitProjectId) ??
+            projects.find((project) => project.scopeId === explicitProjectId) ??
+            null);
+    }
+    const activeProjectName = normalizeNonEmpty(options.activeProjectName);
+    if (activeProjectName) {
+        const active = projects.find((project) => matchProjectByName(project, activeProjectName));
+        if (active)
+            return active;
+    }
+    return projects[0] ?? null;
+}
+export async function resolveProjectBindingContext(options, params = {}) {
+    const requireProject = params.requireProject === true;
+    const { rootDir, configPath, config } = await loadAopsRepoConfig(process.cwd());
+    const explicitScopeId = normalizeNonEmpty(options.scopeId);
+    const explicitProjectId = normalizeNonEmpty(options.projectId);
+    const explicitProjectName = normalizeNonEmpty(options.projectName);
+    const explicitProjectSlug = normalizeNonEmpty(options.projectSlug);
+    const explicitId = explicitProjectId ?? explicitScopeId;
+    const configProject = config
+        ? resolveProjectFromConfig(config.projects, {
+            scopeId: explicitScopeId,
+            projectId: explicitProjectId,
+            projectName: explicitProjectName,
+            projectSlug: explicitProjectSlug,
+            activeProjectName: config.activeProjectName,
+        })
+        : null;
+    const projectId = explicitProjectId ??
+        explicitScopeId ??
+        configProject?.projectId ??
+        configProject?.scopeId;
+    const scopeId = projectId;
+    const projectName = explicitProjectName ?? configProject?.name;
+    const projectSlug = explicitProjectSlug ?? normalizeNonEmpty(configProject?.slug);
+    const pendingServerProjectLookup = !projectId && !explicitId
+        ? explicitProjectSlug
+            ? { kind: 'slug', value: explicitProjectSlug }
+            : explicitProjectName
+                ? { kind: 'name', value: explicitProjectName }
+                : undefined
+        : undefined;
+    if (requireProject && !scopeId && !projectId && !pendingServerProjectLookup) {
+        throw new Error('Project context could not be resolved. Provide --project-id <id>, or --project-slug/--project-name (resolved against the server). `--scope-id` remains a legacy/internal alias.');
+    }
+    return {
+        repoRoot: rootDir,
+        configPath,
+        scopeId: scopeId ?? projectId,
+        projectId,
+        projectName,
+        projectSlug,
+        localRoot: normalizeNonEmpty(configProject?.localRoot),
+        ownerRepo: normalizeNonEmpty(configProject?.ownerRepo),
+        parentProjectSlug: normalizeNonEmpty(configProject?.parentProjectSlug),
+        configFound: Boolean(config),
+        ...(pendingServerProjectLookup ? { pendingServerProjectLookup } : {}),
+    };
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function unwrapHostedEntityRecord(payload) {
+    let current = payload;
+    if (isRecord(current) && Object.prototype.hasOwnProperty.call(current, 'response')) {
+        current = current.response;
+    }
+    for (let depth = 0; depth < 6 && isRecord(current); depth += 1) {
+        const record = current;
+        if (normalizeNonEmpty(record.id) ??
+            normalizeNonEmpty(record.projectId) ??
+            normalizeNonEmpty(record.slug)) {
+            return record;
+        }
+        if (Object.prototype.hasOwnProperty.call(record, 'data')) {
+            current = record.data;
+            continue;
+        }
+        return record;
+    }
+    return isRecord(current) ? current : null;
+}
+function unwrapHostedEntityRows(payload) {
+    let current = payload;
+    if (isRecord(current) && Object.prototype.hasOwnProperty.call(current, 'response')) {
+        current = current.response;
+    }
+    for (let depth = 0; depth < 6; depth += 1) {
+        if (Array.isArray(current))
+            break;
+        if (isRecord(current) && Array.isArray(current.items)) {
+            current = current.items;
+            break;
+        }
+        if (isRecord(current) && Object.prototype.hasOwnProperty.call(current, 'data')) {
+            current = current.data;
+            continue;
+        }
+        break;
+    }
+    if (!Array.isArray(current))
+        return [];
+    return current.filter((entry) => isRecord(entry));
+}
+export async function hydrateProjectContextFromServer(context, deps) {
+    const projectId = normalizeNonEmpty(context.projectId) ?? normalizeNonEmpty(context.scopeId);
+    if (!projectId) {
+        throw new Error('Cannot verify project against server without a resolved project id. Provide --project-id <id>.');
+    }
+    const payload = await deps.invokeHostedTool({
+        toolId: 'agentspace.project.get-by-id',
+        input: { id: projectId },
+    });
+    const project = unwrapHostedEntityRecord(payload);
+    if (!project) {
+        throw new Error(`Project ${projectId} not found on server.`);
+    }
+    const scopeId = normalizeNonEmpty(project.scopeId) ??
+        normalizeNonEmpty(project.id) ??
+        normalizeNonEmpty(project.projectId) ??
+        context.scopeId ??
+        projectId;
+    return {
+        ...context,
+        scopeId,
+        projectId: normalizeNonEmpty(project.id) ?? normalizeNonEmpty(project.projectId) ?? projectId,
+        projectName: normalizeNonEmpty(project.name) ?? context.projectName,
+        projectSlug: normalizeNonEmpty(project.slug) ?? context.projectSlug,
+    };
+}
+function normalizeLookupKey(value) {
+    return normalizeNonEmpty(value)?.toLowerCase();
+}
+export async function resolveProjectIdFromServer(value, kind, deps) {
+    const normalizedValue = normalizeLookupKey(value);
+    if (!normalizedValue) {
+        throw new Error(`Project ${kind} is required to resolve a project id from the server.`);
+    }
+    const payload = await deps.invokeHostedTool({
+        toolId: 'agentspace.project.list-projects',
+        input: {},
+    });
+    const rows = unwrapHostedEntityRows(payload);
+    const matches = rows.filter((row) => normalizeLookupKey(kind === 'slug' ? row.slug : row.name) === normalizedValue);
+    if (matches.length === 0) {
+        throw new Error(`Project ${kind} '${value}' not found on the server.`);
+    }
+    if (matches.length > 1) {
+        const candidates = matches
+            .map((row) => {
+            const id = normalizeNonEmpty(row.id) ?? normalizeNonEmpty(row.projectId) ?? '(no id)';
+            const label = normalizeNonEmpty(row.name) ?? normalizeNonEmpty(row.slug) ?? '(unnamed)';
+            return `${label} (${id})`;
+        })
+            .join(', ');
+        throw new Error(`Project ${kind} '${value}' is ambiguous on the server. Candidates: ${candidates}.`);
+    }
+    const project = matches[0];
+    const projectId = normalizeNonEmpty(project.id) ?? normalizeNonEmpty(project.projectId);
+    if (!projectId) {
+        throw new Error(`Project ${kind} '${value}' resolved a record without an id on the server.`);
+    }
+    const scopeId = normalizeNonEmpty(project.scopeId) ?? projectId;
+    return {
+        projectId,
+        scopeId,
+        name: normalizeNonEmpty(project.name),
+        slug: normalizeNonEmpty(project.slug),
+    };
+}
+export async function hydrateProjectIdFromServerLookup(context, deps) {
+    const pending = context.pendingServerProjectLookup;
+    if (!pending || normalizeNonEmpty(context.projectId)) {
+        return context;
+    }
+    const resolved = await resolveProjectIdFromServer(pending.value, pending.kind, deps);
+    const { pendingServerProjectLookup: _consumed, ...rest } = context;
+    return {
+        ...rest,
+        projectId: resolved.projectId,
+        scopeId: resolved.scopeId,
+        projectName: resolved.name ?? context.projectName,
+        projectSlug: resolved.slug ?? context.projectSlug,
+    };
+}
+export function preferProjectNameBinding(context) {
+    const projectName = normalizeNonEmpty(context.projectName);
+    return projectName ? { projectName } : {};
+}
+export function resolveOwnerScopeIdFromBinding(context) {
+    return normalizeNonEmpty(context.scopeId) ?? normalizeNonEmpty(context.projectId);
+}
+export function resolveOwnerScopeIdFromProjectRecord(project, fallback) {
+    return (normalizeNonEmpty(project?.scopeId) ??
+        normalizeNonEmpty(fallback) ??
+        normalizeNonEmpty(project?.id) ??
+        normalizeNonEmpty(project?.projectId));
+}

package/dist/utils/prompts.js

@@ -0,0 +1,70 @@
+import inquirer from 'inquirer';
+const DONE_PREFIX = '\u2714 ';
+const PROMPT_THEME = { prefix: { idle: '?', done: DONE_PREFIX } };
+const normalizePromptMessage = (message) => message.trimStart();
+export async function promptInput(opts) {
+    const { value } = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'value',
+            message: normalizePromptMessage(opts.message),
+            default: opts.default,
+            validate: opts.validate,
+            theme: PROMPT_THEME,
+        },
+    ]);
+    return String(value ?? '');
+}
+export async function promptPassword(opts) {
+    const { value } = await inquirer.prompt([
+        {
+            type: 'password',
+            name: 'value',
+            message: normalizePromptMessage(opts.message),
+            default: opts.default,
+            mask: '*',
+            validate: opts.validate,
+            theme: PROMPT_THEME,
+        },
+    ]);
+    return String(value ?? '');
+}
+export async function promptConfirm(opts) {
+    const { confirm } = await inquirer.prompt([
+        {
+            type: 'confirm',
+            name: 'confirm',
+            message: normalizePromptMessage(opts.message),
+            default: opts.default ?? true,
+            theme: PROMPT_THEME,
+        },
+    ]);
+    return Boolean(confirm);
+}
+export async function promptSelect(opts) {
+    const resolvedType = opts.type === 'list' || !opts.type ? 'select' : opts.type;
+    const { value } = await inquirer.prompt([
+        {
+            type: resolvedType,
+            name: 'value',
+            message: normalizePromptMessage(opts.message),
+            choices: opts.choices,
+            default: opts.default,
+            pageSize: opts.pageSize,
+            theme: PROMPT_THEME,
+        },
+    ]);
+    return String(value);
+}
+export async function promptMultiSelect(opts) {
+    const { values } = await inquirer.prompt([
+        {
+            type: 'checkbox',
+            name: 'values',
+            message: normalizePromptMessage(opts.message),
+            choices: opts.choices,
+            theme: PROMPT_THEME,
+        },
+    ]);
+    return Array.isArray(values) ? values.map((v) => String(v)) : [];
+}

package/dist/utils/refresh-race.js

@@ -0,0 +1,28 @@
+export function createRefreshRaceRecovery(options) {
+    const maxAttempts = Math.max(1, Math.floor(options.maxAttempts ?? 5));
+    const baseDelay = Math.max(0, Math.floor(options.delayMs ?? 50));
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    return async () => {
+        const previousRefresh = options.getCurrentRefreshToken();
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            let latest = null;
+            try {
+                latest = await options.readLatestTokens();
+            }
+            catch {
+                latest = null;
+            }
+            if (latest &&
+                latest.accessToken &&
+                latest.refreshToken &&
+                latest.refreshToken !== previousRefresh) {
+                options.applyTokens(latest);
+                return true;
+            }
+            if (attempt < maxAttempts - 1 && baseDelay > 0) {
+                await sleep(baseDelay * (attempt + 1));
+            }
+        }
+        return false;
+    };
+}

package/dist/utils/repo-config.js

@@ -0,0 +1,109 @@
+import { existsSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { buildOperatorRepoConfig, findWorkspaceRoot, normalizeOperatorRepoConfig, resolveRepoConfigPath, } from './operator-runtime.js';
+export { resolveRepoConfigPath };
+export function serializeAopsRepoConfig(config) {
+    return `${JSON.stringify(config, null, 2)}\n`;
+}
+export function buildAopsRepoConfig(params) {
+    return buildOperatorRepoConfig(params);
+}
+function normalizeString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+function normalizeProjectAuthoringMode(value) {
+    return value === 'local' || value === 'hosted-only' ? value : undefined;
+}
+function rawProjectKey(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const record = raw;
+    return normalizeString(record.projectId) ?? normalizeString(record.slug) ?? normalizeString(record.name);
+}
+function mergeAopsProjectExtensions(normalized, rawProjects) {
+    const candidates = [
+        normalized.projectId,
+        normalized.slug,
+        normalized.name,
+    ].filter((entry) => Boolean(entry));
+    const raw = rawProjects.find((entry) => {
+        const key = rawProjectKey(entry);
+        return key ? candidates.includes(key) : false;
+    });
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return normalized;
+    const record = raw;
+    return {
+        ...normalized,
+        ...(normalizeProjectAuthoringMode(record.authoringMode) ? { authoringMode: normalizeProjectAuthoringMode(record.authoringMode) } : {}),
+        ...(normalizeString(record.localRoot) ? { localRoot: normalizeString(record.localRoot) } : {}),
+        ...(normalizeString(record.ownerRepo) ? { ownerRepo: normalizeString(record.ownerRepo) } : {}),
+        ...(normalizeString(record.parentProjectSlug) ? { parentProjectSlug: normalizeString(record.parentProjectSlug) } : {}),
+    };
+}
+export function normalizeAopsRepoConfig(raw) {
+    const normalized = normalizeOperatorRepoConfig(raw);
+    if (!normalized)
+        return null;
+    const rawProjects = raw && typeof raw === 'object' && !Array.isArray(raw) && Array.isArray(raw.projects)
+        ? raw.projects
+        : [];
+    return {
+        ...normalized,
+        projects: normalized.projects.map((project) => mergeAopsProjectExtensions(project, rawProjects)),
+    };
+}
+export async function readAopsRepoConfig(rootDir) {
+    const configPath = resolveRepoConfigPath(rootDir);
+    if (!existsSync(configPath))
+        return null;
+    try {
+        const rawContent = await fs.readFile(configPath, 'utf8');
+        const parsed = JSON.parse(rawContent);
+        const normalized = normalizeAopsRepoConfig(parsed);
+        if (!normalized)
+            return null;
+        const serialized = serializeAopsRepoConfig(normalized);
+        if (rawContent !== serialized) {
+            await fs.writeFile(configPath, serialized, 'utf8');
+        }
+        return normalized;
+    }
+    catch {
+        return null;
+    }
+}
+export async function readAopsRepoConfigReadOnly(rootDir) {
+    const configPath = resolveRepoConfigPath(rootDir);
+    if (!existsSync(configPath))
+        return null;
+    try {
+        const rawContent = await fs.readFile(configPath, 'utf8');
+        const parsed = JSON.parse(rawContent);
+        return normalizeAopsRepoConfig(parsed);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeAopsRepoConfig(configPath, config) {
+    await fs.writeFile(configPath, serializeAopsRepoConfig(config), 'utf8');
+}
+export async function loadAopsRepoConfig(startDir = process.cwd()) {
+    const rootDir = findWorkspaceRoot(startDir);
+    const configPath = resolveRepoConfigPath(rootDir);
+    return {
+        rootDir,
+        configPath,
+        config: await readAopsRepoConfig(rootDir),
+    };
+}
+export async function loadAopsRepoConfigReadOnly(startDir = process.cwd()) {
+    const rootDir = findWorkspaceRoot(startDir);
+    const configPath = resolveRepoConfigPath(rootDir);
+    return {
+        rootDir,
+        configPath,
+        config: await readAopsRepoConfigReadOnly(rootDir),
+    };
+}

package/dist/utils/repo-first-projectman.js

@@ -0,0 +1,194 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { compactPayload, normalizeNonEmpty } from './command.js';
+import { parseFrontmatterDocument, renderFrontmatterDocument, } from './memory-workspace.js';
+import { resolveRepoFirstWorkspaceRelativeRoot, resolveRepoFirstWorkspaceRoot } from './repo-first-storage.js';
+import { writeFileWithRetry } from './transient-fs.js';
+const SYNC_STATES = new Set(['local', 'synced', 'dirty', 'deleted', 'conflict']);
+function hashContent(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function isAopsArchivePath(filePath) {
+    const parts = filePath.split(path.sep);
+    const aopsIndex = parts.lastIndexOf('.aops');
+    return aopsIndex >= 0 && parts[aopsIndex + 1] === 'archive';
+}
+function comparableRecordHash(record) {
+    const frontmatter = { ...record.frontmatter };
+    delete frontmatter.baseHash;
+    return hashContent(renderFrontmatterDocument(frontmatter, record.body));
+}
+function isProjectmanTombstoneRecord(record) {
+    return record.filePath.includes(`${path.sep}tombstones${path.sep}`);
+}
+function effectiveSyncState(record) {
+    const syncState = ensureSyncState(record.frontmatter.syncState);
+    if (syncState === 'synced' && isProjectmanTombstoneRecord(record))
+        return 'synced';
+    const baseHash = normalizeNonEmpty(record.frontmatter.baseHash);
+    if (syncState === 'synced' && baseHash && comparableRecordHash(record) !== baseHash)
+        return 'dirty';
+    return syncState;
+}
+function ensureSyncState(value) {
+    const normalized = normalizeNonEmpty(value);
+    return normalized && SYNC_STATES.has(normalized) ? normalized : 'local';
+}
+export function resolveRepoFirstProjectmanPaths(context) {
+    const root = path.join(resolveRepoFirstWorkspaceRoot(context), 'projectman');
+    return {
+        root,
+        boards: path.join(root, 'boards'),
+        tasks: path.join(root, 'kanban-tasks'),
+        sprints: path.join(root, 'sprints'),
+        utasks: path.join(root, 'utasks'),
+        issues: path.join(root, 'issues'),
+        feedback: path.join(root, 'feedback'),
+        reviewRequests: path.join(root, 'review-requests'),
+        tombstones: path.join(root, 'tombstones'),
+        views: path.join(root, 'views'),
+    };
+}
+export function resolveRepoFirstAgentspacePaths(context) {
+    const root = path.join(resolveRepoFirstWorkspaceRoot(context), 'agentspace');
+    const discussions = path.join(root, 'discussions');
+    const memory = path.join(root, 'memory');
+    const experience = path.join(root, 'experience');
+    return {
+        root,
+        discussions,
+        discussionTopics: path.join(discussions, 'topics'),
+        experience,
+        experienceItems: path.join(experience, 'items'),
+        experienceViews: path.join(experience, 'views'),
+        memory,
+        memoryItems: path.join(memory, 'items'),
+        memoryViews: path.join(memory, 'views'),
+        synopsis: path.join(root, 'synopsis.md'),
+    };
+}
+function entityDir(context, entityType) {
+    const paths = resolveRepoFirstProjectmanPaths(context);
+    switch (entityType) {
+        case 'projectman.board':
+            return paths.boards;
+        case 'projectman.kanban-task':
+            return paths.tasks;
+        case 'projectman.sprint':
+            return paths.sprints;
+        case 'projectman.issue':
+            return paths.issues;
+        case 'projectman.feedback':
+            return paths.feedback;
+        case 'projectman.review-request':
+            return paths.reviewRequests;
+        default:
+            throw new Error(`Unsupported Projectman entity type "${entityType}".`);
+    }
+}
+async function readMarkdownRecords(rootDir, params = {}) {
+    try {
+        const entries = await fs.readdir(rootDir, { withFileTypes: true });
+        const records = [];
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            const filePath = path.join(rootDir, entry.name);
+            if (isAopsArchivePath(filePath))
+                continue;
+            if (entry.isDirectory() && params.recursive === true) {
+                records.push(...await readMarkdownRecords(filePath, params));
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.endsWith('.md'))
+                continue;
+            const raw = await fs.readFile(filePath, 'utf8');
+            const parsed = parseFrontmatterDocument(raw);
+            records.push({ filePath, frontmatter: parsed.frontmatter, body: parsed.body });
+        }
+        return records;
+    }
+    catch {
+        return [];
+    }
+}
+async function readEntityRecords(context, entityType) {
+    if (entityType === 'projectman.utask') {
+        return readMarkdownRecords(resolveRepoFirstProjectmanPaths(context).utasks, { recursive: true });
+    }
+    return readMarkdownRecords(entityDir(context, entityType));
+}
+function materializeRecord(record) {
+    const archivedAt = normalizeNonEmpty(record.frontmatter.archivedAt);
+    return compactPayload({
+        ...record.frontmatter,
+        id: normalizeNonEmpty(record.frontmatter.localId) ?? normalizeNonEmpty(record.frontmatter.id),
+        archivedAt,
+        archived: Boolean(archivedAt),
+        body: record.body,
+    });
+}
+async function listEntities(context, entityType) {
+    return (await readEntityRecords(context, entityType)).map(materializeRecord);
+}
+export async function rebuildProjectmanViews(context) {
+    const paths = resolveRepoFirstProjectmanPaths(context);
+    const [boards, tasks, sprints, issues, feedback, reviewRequests] = await Promise.all([
+        listEntities(context, 'projectman.board'),
+        listEntities(context, 'projectman.kanban-task'),
+        listEntities(context, 'projectman.sprint'),
+        listEntities(context, 'projectman.issue'),
+        listEntities(context, 'projectman.feedback'),
+        listEntities(context, 'projectman.review-request'),
+    ]);
+    const sourceRoot = `${resolveRepoFirstWorkspaceRelativeRoot(context)}/projectman/**`;
+    const lines = [
+        '# Projectman Workspace (read-only local cache)',
+        '',
+        `> Read-only local cache of hosted Projectman records, mirrored under \`${sourceRoot}\`. The server is the source of truth.`,
+        '',
+        `- Boards: ${boards.length}`,
+        `- Kanban Tasks: ${tasks.length}`,
+        `- Sprints: ${sprints.length}`,
+        `- Issues: ${issues.length}`,
+        `- Feedback: ${feedback.length}`,
+        `- Review requests: ${reviewRequests.length}`,
+        '',
+        '## Boards',
+        ...boards.map((board) => `- ${normalizeNonEmpty(board.name) ?? normalizeNonEmpty(board.slug) ?? normalizeNonEmpty(board.id)}`),
+        '',
+        '## Active Tasks',
+        ...tasks.map((task) => `- ${normalizeNonEmpty(task.title) ?? normalizeNonEmpty(task.id)} — ${normalizeNonEmpty(task.columnSlug) ?? 'unknown'}`),
+    ];
+    await fs.mkdir(paths.views, { recursive: true });
+    await writeFileWithRetry(path.join(paths.views, 'index.md'), `${lines.join('\n')}\n`, 'utf8');
+}
+export async function collectRepoFirstSyncRecords(context) {
+    const repoRoot = typeof context === 'string' ? context : context.repoRoot;
+    const projectman = resolveRepoFirstProjectmanPaths(context);
+    const agentspace = resolveRepoFirstAgentspacePaths(context);
+    const records = [
+        ...await readMarkdownRecords(projectman.boards),
+        ...await readMarkdownRecords(projectman.tasks),
+        ...await readMarkdownRecords(projectman.sprints),
+        ...await readMarkdownRecords(projectman.utasks, { recursive: true }),
+        ...await readMarkdownRecords(projectman.issues),
+        ...await readMarkdownRecords(projectman.feedback),
+        ...await readMarkdownRecords(projectman.reviewRequests),
+        ...await readMarkdownRecords(projectman.tombstones, { recursive: true }),
+        ...await readMarkdownRecords(agentspace.experienceItems),
+        ...await readMarkdownRecords(agentspace.memoryItems),
+    ];
+    return records.map((record) => {
+        const declaredSyncState = ensureSyncState(record.frontmatter.syncState);
+        const currentSyncState = effectiveSyncState(record);
+        return compactPayload({
+            path: path.relative(repoRoot, record.filePath).split(path.sep).join('/'),
+            entityType: normalizeNonEmpty(record.frontmatter.entityType),
+            localId: normalizeNonEmpty(record.frontmatter.localId),
+            remoteId: normalizeNonEmpty(record.frontmatter.remoteId),
+            syncState: currentSyncState,
+            declaredSyncState: declaredSyncState !== currentSyncState ? declaredSyncState : undefined,
+            hash: hashContent(renderFrontmatterDocument(record.frontmatter, record.body)),
+        });
+    });
+}

package/dist/utils/repo-first-storage.js

@@ -0,0 +1,13 @@
+import path from 'node:path';
+import { normalizeNonEmpty } from './command.js';
+export function resolveRepoFirstWorkspaceRoot(context) {
+    const repoRoot = typeof context === 'string' ? context : context.repoRoot;
+    const localRoot = typeof context === 'string' ? undefined : normalizeNonEmpty(context.localRoot);
+    if (!localRoot)
+        return path.join(repoRoot, '.aops');
+    return path.isAbsolute(localRoot) ? localRoot : path.join(repoRoot, localRoot);
+}
+export function resolveRepoFirstWorkspaceRelativeRoot(context) {
+    const repoRoot = typeof context === 'string' ? context : context.repoRoot;
+    return path.relative(repoRoot, resolveRepoFirstWorkspaceRoot(context)).split(path.sep).join('/') || '.';
+}