@aopslabs/aops 0.3.33 → 0.3.34

package/aops-assets-release/docs/user-guides/aops-cli-user-guide.md

@@ -220,6 +220,9 @@ is canonical, so the cache is only ever pulled, never pushed back.
 ```bash
 aops-cli sync status --project-slug aops --json
 aops-cli sync pull --project-slug aops --apply --json
+aops-cli sync pull --project-slug aops --only projectman --apply --json
+aops-cli sync pull --project-slug aops --only agentspace --apply --json
+aops-cli sync pull --hosted-project-slug aops --only hosted-skills --apply --json
 aops-cli sync status --all-projects --json
 aops-cli sync pull --all-projects --apply --json
 ```
@@ -238,6 +241,13 @@ Rules:
    reported/skipped rather than treated as another project's cache.
 4. Because the server is canonical, conflict/drift resolution is not part of the
    pull: a refresh simply overwrites the local cache with current server state.
+5. `sync pull` and `sync bootstrap` accept repeatable `--only` flags with
+   `projectman`, `agentspace`, `hosted-skills`, and `hosted-prompts`. Omitting
+   `--only` preserves the complete refresh. Prefer a scoped synchronous pull
+   when only one cache family changed so completion and errors remain visible.
+6. Docman is intentionally not a sync partition. Refresh document mirrors with
+   `aops-cli doc mirror pull`; `--only docman` is rejected rather than silently
+   doing the wrong operation.
 
 #### 13.1.3 Archive lifecycle
 

package/dist/commands/repo-sync.js

@@ -17,6 +17,26 @@ import { loadAopsRepoConfig, loadAopsRepoConfigReadOnly, readAopsRepoConfigReadO
 import { hostedProjectKey, rebuildHostedWorkspace, syncHostedMirrorKind, } from '../utils/hosted-workspace.js';
 import { GUIDE_PATHS } from '../utils/guide-paths.js';
 import { writeFileWithRetry } from '../utils/transient-fs.js';
+export const SYNC_PULL_PARTITIONS = [
+    'projectman',
+    'agentspace',
+    'hosted-skills',
+    'hosted-prompts',
+];
+export function resolveSyncPullPartitions(values = []) {
+    if (values.length === 0)
+        return [...SYNC_PULL_PARTITIONS];
+    const allowed = new Set(SYNC_PULL_PARTITIONS);
+    const selected = new Set();
+    for (const raw of values) {
+        const value = normalizeNonEmpty(raw)?.toLowerCase();
+        if (!value || !allowed.has(value)) {
+            throw new Error(`Unknown sync partition: ${raw || '(empty)'}. Expected one of: ${SYNC_PULL_PARTITIONS.join(', ')}.`);
+        }
+        selected.add(value);
+    }
+    return SYNC_PULL_PARTITIONS.filter((partition) => selected.has(partition));
+}
 function projectReportBase(project) {
     return compactPayload({
         projectSlug: normalizeNonEmpty(project.slug),
@@ -1091,18 +1111,22 @@ async function resolveHostedMirrorTargets(apiState, options, context) {
     }
     return [...deduped.values()];
 }
-async function buildHostedMirrorItemsForProject(apiState, options, project) {
+async function buildHostedMirrorItemsForProject(apiState, options, project, selection = { skills: true, prompts: true }) {
     const scopeId = normalizeNonEmpty(project.scopeId) ?? normalizeNonEmpty(project.projectId);
     if (!scopeId)
         return { skillItems: [], promptItems: [] };
     const [skills, prompts] = await Promise.all([
-        toRecordArray(await invokeRead(apiState, options, 'agentspace.skill.list-skills', {
-            filter: compactPayload({ scopeId, scopeResolution: 'cascade' }),
-            options: { limit: 500 },
-        })),
-        toRecordArray(await invokeRead(apiState, options, 'agentspace.prompt.list-prompts', {
-            filter: compactPayload({ scopeId, scopeResolution: 'cascade', limit: 500 }),
-        })),
+        selection.skills
+            ? toRecordArray(await invokeRead(apiState, options, 'agentspace.skill.list-skills', {
+                filter: compactPayload({ scopeId, scopeResolution: 'cascade' }),
+                options: { limit: 500 },
+            }))
+            : [],
+        selection.prompts
+            ? toRecordArray(await invokeRead(apiState, options, 'agentspace.prompt.list-prompts', {
+                filter: compactPayload({ scopeId, scopeResolution: 'cascade', limit: 500 }),
+            }))
+            : [],
     ]);
     const skillItems = await Promise.all(skills.map(async (skill) => {
         const currentVersionId = normalizeNonEmpty(skill.currentVersionId);
@@ -1224,24 +1248,34 @@ async function runSyncDiff(options) {
 async function collectSyncPullData(options, command, context, apiState) {
     const projectId = normalizeNonEmpty(context.projectId);
     const scopeId = normalizeNonEmpty(context.scopeId) ?? projectId;
+    const partitions = resolveSyncPullPartitions(options.only);
+    const selected = new Set(partitions);
+    const pullProjectman = selected.has('projectman');
+    const pullAgentspace = selected.has('agentspace');
+    const pullHostedSkills = selected.has('hosted-skills');
+    const pullHostedPrompts = selected.has('hosted-prompts');
     const pmPaths = resolveRepoFirstProjectmanPaths(context);
     const agPaths = resolveRepoFirstAgentspacePaths(context);
     const filesWritten = [];
     const [boards, tasks, sprints, issues, feedback, reviewRequests, experiences, memories] = await Promise.all([
-        invokeRead(apiState, options, 'projectman.kanban-board.list', compactPayload({ scopeId, project: projectId })),
-        invokeRead(apiState, options, 'projectman.kanban-task.list', compactPayload({ scopeId, project: projectId })),
-        invokeRead(apiState, options, 'projectman.sprint.list', compactPayload({ scopeId, project: projectId })),
-        invokeRead(apiState, options, 'projectman.issue.list', compactPayload({ scopeId })),
-        invokeRead(apiState, options, 'projectman.feedback.list', compactPayload({ scopeId })),
-        invokeRead(apiState, options, 'projectman.review-request.list', compactPayload({ scopeId })),
-        invokeRead(apiState, options, 'agentspace.experience-item.list-experience-items', {
-            filter: compactPayload({ scopeId, scopeResolution: 'cascade' }),
-            options: { limit: 500 },
-        }),
-        invokeRead(apiState, options, 'agentspace.memory-item.list-memory-items', {
-            filter: compactPayload({ scopeId, scopeResolution: 'cascade', projectId }),
-            options: { limit: 500 },
-        }),
+        pullProjectman ? invokeRead(apiState, options, 'projectman.kanban-board.list', compactPayload({ scopeId, project: projectId })) : [],
+        pullProjectman ? invokeRead(apiState, options, 'projectman.kanban-task.list', compactPayload({ scopeId, project: projectId })) : [],
+        pullProjectman ? invokeRead(apiState, options, 'projectman.sprint.list', compactPayload({ scopeId, project: projectId })) : [],
+        pullProjectman ? invokeRead(apiState, options, 'projectman.issue.list', compactPayload({ scopeId })) : [],
+        pullProjectman ? invokeRead(apiState, options, 'projectman.feedback.list', compactPayload({ scopeId })) : [],
+        pullProjectman ? invokeRead(apiState, options, 'projectman.review-request.list', compactPayload({ scopeId })) : [],
+        pullAgentspace
+            ? invokeRead(apiState, options, 'agentspace.experience-item.list-experience-items', {
+                filter: compactPayload({ scopeId, scopeResolution: 'cascade' }),
+                options: { limit: 500 },
+            })
+            : [],
+        pullAgentspace
+            ? invokeRead(apiState, options, 'agentspace.memory-item.list-memory-items', {
+                filter: compactPayload({ scopeId, scopeResolution: 'cascade', projectId }),
+                options: { limit: 500 },
+            })
+            : [],
     ]);
     for (const row of toRecordArray(boards)) {
         const remoteId = normalizeNonEmpty(row.id);
@@ -1295,29 +1329,42 @@ async function collectSyncPullData(options, command, context, apiState) {
     for (const row of toRecordArray(memories)) {
         filesWritten.push(await writeMemorySeedFile({ repoRoot: context.repoRoot, dir: agPaths.memoryItems, remote: row, projectId, scopeId }));
     }
-    const hostedMirrorTargets = await resolveHostedMirrorTargets(apiState, options, context);
-    const touchedHostedProjectKeys = hostedMirrorTargets.map((target) => hostedProjectKey(target));
-    const hostedSkillItems = [];
-    const hostedPromptItems = [];
-    for (const target of hostedMirrorTargets) {
-        const mirrorItems = await buildHostedMirrorItemsForProject(apiState, options, target);
-        hostedSkillItems.push(...mirrorItems.skillItems);
-        hostedPromptItems.push(...mirrorItems.promptItems);
-    }
-    filesWritten.push(...await syncHostedMirrorKind(context.repoRoot, 'skill', hostedSkillItems, { touchedProjectKeys: touchedHostedProjectKeys }));
-    filesWritten.push(...await syncHostedMirrorKind(context.repoRoot, 'prompt', hostedPromptItems, { touchedProjectKeys: touchedHostedProjectKeys }));
-    await rebuildProjectmanViews(context);
-    const experienceItems = await readExperienceItems(agPaths.experienceItems);
-    await rebuildExperienceWorkspace(context, experienceItems);
-    const memoryItems = await readLocalMemoryEntries(agPaths.memoryItems);
-    await rebuildLocalMemoryWorkspace({
-        ...context,
-        items: memoryItems,
-    });
-    filesWritten.push(...await rebuildHostedWorkspace(context.repoRoot));
+    if (pullHostedSkills || pullHostedPrompts) {
+        const hostedMirrorTargets = await resolveHostedMirrorTargets(apiState, options, context);
+        const touchedHostedProjectKeys = hostedMirrorTargets.map((target) => hostedProjectKey(target));
+        const hostedSkillItems = [];
+        const hostedPromptItems = [];
+        for (const target of hostedMirrorTargets) {
+            const mirrorItems = await buildHostedMirrorItemsForProject(apiState, options, target, {
+                skills: pullHostedSkills,
+                prompts: pullHostedPrompts,
+            });
+            hostedSkillItems.push(...mirrorItems.skillItems);
+            hostedPromptItems.push(...mirrorItems.promptItems);
+        }
+        if (pullHostedSkills) {
+            filesWritten.push(...await syncHostedMirrorKind(context.repoRoot, 'skill', hostedSkillItems, { touchedProjectKeys: touchedHostedProjectKeys }));
+        }
+        if (pullHostedPrompts) {
+            filesWritten.push(...await syncHostedMirrorKind(context.repoRoot, 'prompt', hostedPromptItems, { touchedProjectKeys: touchedHostedProjectKeys }));
+        }
+    }
+    if (pullProjectman)
+        await rebuildProjectmanViews(context);
+    if (pullAgentspace) {
+        const experienceItems = await readExperienceItems(agPaths.experienceItems);
+        await rebuildExperienceWorkspace(context, experienceItems);
+        const memoryItems = await readLocalMemoryEntries(agPaths.memoryItems);
+        await rebuildLocalMemoryWorkspace({
+            ...context,
+            items: memoryItems,
+        });
+    }
+    if (pullHostedSkills || pullHostedPrompts)
+        filesWritten.push(...await rebuildHostedWorkspace(context.repoRoot));
     await ensureGitignore(context.repoRoot);
-    const statePath = await writeState(context.repoRoot, { lastPull: { command, filesWritten } });
-    return { filesWritten, statePath };
+    const statePath = await writeState(context.repoRoot, { lastPull: { command, partitions, filesWritten } });
+    return { partitions, filesWritten, statePath };
 }
 async function runSyncPullOrBootstrap(options, command) {
     try {
@@ -1901,6 +1948,10 @@ function applyAllProjectsOption(cmd) {
     cmd.option('--all-projects', 'Run the sync command once per repo-config project and report project-level results without fail-fast');
     return cmd;
 }
+function applySyncPullPartitionOptions(cmd) {
+    cmd.option('--only <partition>', `Limit pull/bootstrap to one partition; repeat as needed (${SYNC_PULL_PARTITIONS.join(', ')})`, collectRepeatedOption, []);
+    return cmd;
+}
 export function makeSyncCommand() {
     const cmd = new Command('sync').description('Server-first sync commands: refresh the read-only local cache of Projectman/Agentspace state plus hosted prompt/skill mirrors');
     applySyncSelectionOptions(applyAllProjectsOption(applySyncOptions(cmd.command('status')
@@ -1909,21 +1960,21 @@ export function makeSyncCommand() {
     applySyncSelectionOptions(applyAllProjectsOption(applySyncOptions(cmd.command('diff')
         .description('Show local records that are not synced')
         .action(async (options) => runSyncDiff(options)))));
-    applyAllProjectsOption(applySyncOptions(cmd.command('pull')
+    applySyncPullPartitionOptions(applyAllProjectsOption(applySyncOptions(cmd.command('pull')
         .description('Pull hosted Projectman/Agentspace state into the read-only local cache and refresh read-only prompt/skill mirrors')
         .option('--apply', 'Write pulled records into the local cache workspace')
         .option('--hosted-project-id <id>', 'Also mirror hosted read-only prompts/skills for another project id', collectRepeatedOption, [])
         .option('--hosted-project-name <name>', 'Also mirror hosted read-only prompts/skills for another project name', collectRepeatedOption, [])
         .option('--hosted-project-slug <slug>', 'Also mirror hosted read-only prompts/skills for another project slug', collectRepeatedOption, [])
-        .action(async (options) => runSyncPullOrBootstrap(options, 'sync.pull'))));
-    applyAllProjectsOption(applySyncOptions(cmd.command('bootstrap')
+        .action(async (options) => runSyncPullOrBootstrap(options, 'sync.pull')))));
+    applySyncPullPartitionOptions(applyAllProjectsOption(applySyncOptions(cmd.command('bootstrap')
         .description('Seed the read-only local cache from hosted server state and refresh read-only prompt/skill mirrors')
         .option('--from-server', 'Bootstrap from hosted AOPS server state')
         .option('--apply', 'Write bootstrapped records into the local cache workspace')
         .option('--hosted-project-id <id>', 'Also mirror hosted read-only prompts/skills for another project id', collectRepeatedOption, [])
         .option('--hosted-project-name <name>', 'Also mirror hosted read-only prompts/skills for another project name', collectRepeatedOption, [])
         .option('--hosted-project-slug <slug>', 'Also mirror hosted read-only prompts/skills for another project slug', collectRepeatedOption, [])
-        .action(async (options) => runSyncPullOrBootstrap(options, 'sync.bootstrap'))));
+        .action(async (options) => runSyncPullOrBootstrap(options, 'sync.bootstrap')))));
     applySyncSelectionOptions(applySyncOptions(cmd.command('sidecar')
         .description('Run a localhost-bound cockpit sidecar that exposes read-only local cache status/diff on the client machine')
         .option('--host <host>', 'Bind host for the sidecar HTTP server', DEFAULT_SIDECAR_HOST)
@@ -1950,6 +2001,7 @@ export function makeSyncCommand() {
             'aops-cli sync pull --apply --json',
             'aops-cli sync pull --all-projects --apply --json',
             'aops-cli sync pull --apply --hosted-project-slug aops --json',
+            'aops-cli sync pull --only hosted-skills --apply --hosted-project-slug aops --json',
             'aops-cli sync resolve --path .aops-cache/projectman/sprints/demo.md --prefer remote --json',
         ],
         guide: GUIDE_PATHS.operator,
@@ -1962,6 +2014,8 @@ export function makeSyncCommand() {
             'Board/task/sprint selection expands to related Projectman records and linked Agentspace memory/experience context. `--record` matches local path, localId, remoteId, slug, name, or title.',
             '`--all-projects` runs status/diff/pull/bootstrap once per repo-config project (server-first; no authoring-mode split), skips only projects without a localRoot in a multi-project repo, and reports project-level errors without fail-fast.',
             '`sync pull` and `sync bootstrap` are project-level merge/mirror commands; use --hosted-project-* there only to refresh hosted prompt/skill mirrors.',
+            '`sync pull|bootstrap --only <partition>` limits work to projectman, agentspace, hosted-skills, or hosted-prompts; repeat --only to combine partitions. Omitting it preserves the full refresh.',
+            'Docman is intentionally separate: use `aops-cli doc mirror pull`, not a sync --only partition.',
             'Hosted writes are the source of truth, so the local cache never replays back. If a cache file drifts, re-run `sync pull` to refresh it from the server; `sync resolve --prefer remote` re-adopts a single record from hosted state.',
             'Browser/cockpit surfaces must never assume the remote aops-server machine has the repo. Use `aops-cli sync sidecar --allow-origin <cockpit-origin>` on the client machine to expose a localhost-only read-only status/diff bridge.',
             '`localId` is UUIDv4. `remoteId` is filled after hosted sync/bootstrap.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aopslabs/aops",
-  "version": "0.3.33",
+  "version": "0.3.34",
   "type": "module",
   "description": "AOPS CLI and terminal setup application.",
   "aopsDockerServerVersion": "0.2.17",
@@ -40,12 +40,12 @@
     "@openai/codex-sdk": "0.149.0",
     "@anthropic-ai/claude-agent-sdk": "0.3.241",
     "@opencode-ai/sdk": "1.18.21",
-    "@aopslabs/aops-server": "0.2.27",
+    "@aopslabs/aops-host-registration": "0.2.3",
     "@aopslabs/aops-pg-bootstrap": "0.2.9",
-    "@aopslabs/aops-runtime-config": "0.2.3",
-    "@aopslabs/api-client": "0.2.3",
+    "@aopslabs/aops-server": "0.2.28",
     "@aopslabs/aops-agent-runtime": "0.1.1",
-    "@aopslabs/aops-host-registration": "0.2.3"
+    "@aopslabs/aops-runtime-config": "0.2.3",
+    "@aopslabs/api-client": "0.2.3"
   },
   "devDependencies": {
     "@types/node": "25.3.1",