sh3-core 0.20.1 → 0.20.2

package/dist/shell-shard/verbs/ls.js

@@ -0,0 +1,48 @@
+import { parseScopePath } from './scope-parse';
+export const lsVerb = {
+    name: 'ls',
+    summary: 'List documents. Usage: ls | ls <shardId> | ls <shardId>/<prefix>',
+    programmatic: true,
+    async run(ctx, args) {
+        var _a, _b, _c;
+        const ts = Date.now();
+        if (!ctx.docs) {
+            ctx.scrollback.push({ kind: 'status', text: 'ls: document capability not available', level: 'error', ts });
+            return;
+        }
+        const all = await ctx.docs.listDocuments();
+        const arg = args[0];
+        if (!arg) {
+            // Group by shard, emit counts
+            const counts = new Map();
+            for (const doc of all) {
+                counts.set(doc.shardId, ((_a = counts.get(doc.shardId)) !== null && _a !== void 0 ? _a : 0) + 1);
+            }
+            if (counts.size === 0) {
+                ctx.scrollback.push({ kind: 'status', text: 'ls: no documents in active scope', level: 'info', ts });
+                return;
+            }
+            const lines = [...counts.entries()]
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([shard, count]) => `  ${shard.padEnd(24)} ${count} doc${count !== 1 ? 's' : ''}`);
+            ctx.scrollback.push({ kind: 'text', stream: 'stdout', chunks: [lines.join('\n') + '\n'], ts });
+            return;
+        }
+        const parsed = parseScopePath(arg);
+        const shardId = (_b = parsed === null || parsed === void 0 ? void 0 : parsed.shardId) !== null && _b !== void 0 ? _b : arg;
+        const prefix = (_c = parsed === null || parsed === void 0 ? void 0 : parsed.path) !== null && _c !== void 0 ? _c : '';
+        const docs = all.filter((d) => {
+            if (d.shardId !== shardId)
+                return false;
+            return prefix ? d.path.startsWith(prefix) : true;
+        });
+        if (docs.length === 0) {
+            ctx.scrollback.push({ kind: 'status', text: `ls: no documents in ${arg}`, level: 'info', ts });
+            return;
+        }
+        const lines = docs
+            .sort((a, b) => a.path.localeCompare(b.path))
+            .map((d) => `  ${d.path}`);
+        ctx.scrollback.push({ kind: 'text', stream: 'stdout', chunks: [lines.join('\n') + '\n'], ts });
+    },
+};

package/dist/shell-shard/verbs/ls.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shell-shard/verbs/ls.test.js

@@ -0,0 +1,64 @@
+import { describe, it, expect, vi } from 'vitest';
+import { lsVerb } from './ls';
+function makeDocs(overrides = {}) {
+    return Object.assign({ listDocuments: vi.fn(async () => []), listShards: vi.fn(async () => []), watchDocuments: vi.fn(() => () => { }) }, overrides);
+}
+function makeCtx(docs) {
+    const pushed = [];
+    const ctx = {
+        sh3: {},
+        scrollback: { push: (e) => pushed.push(e) },
+        session: {},
+        cwd: '/',
+        fs: {},
+        docs,
+        dispatch: async () => { },
+    };
+    return { ctx, pushed };
+}
+const sampleDocs = [
+    { shardId: 'notes', path: 'draft.md', size: 100, lastModified: 0 },
+    { shardId: 'notes', path: 'ideas/spark.md', size: 50, lastModified: 0 },
+    { shardId: 'design', path: 'spec.guml', size: 200, lastModified: 0 },
+];
+describe('ls verb', () => {
+    it('emits error when docs capability missing', async () => {
+        const { ctx, pushed } = makeCtx(undefined);
+        await lsVerb.run(ctx, []);
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err).toBeDefined();
+    });
+    it('lists shards with doc counts when no args', async () => {
+        const docs = makeDocs({ listDocuments: vi.fn(async () => sampleDocs) });
+        const { ctx, pushed } = makeCtx(docs);
+        await lsVerb.run(ctx, []);
+        const text = pushed.find((e) => e.kind === 'text');
+        expect(text === null || text === void 0 ? void 0 : text.chunks.join('')).toMatch(/notes/);
+        expect(text === null || text === void 0 ? void 0 : text.chunks.join('')).toMatch(/design/);
+        expect(text === null || text === void 0 ? void 0 : text.chunks.join('')).toMatch(/2/); // notes has 2 docs
+    });
+    it('lists docs in a specific shard', async () => {
+        const docs = makeDocs({ listDocuments: vi.fn(async () => sampleDocs) });
+        const { ctx, pushed } = makeCtx(docs);
+        await lsVerb.run(ctx, ['notes']);
+        const text = pushed.find((e) => e.kind === 'text');
+        expect(text === null || text === void 0 ? void 0 : text.chunks.join('')).toMatch(/draft\.md/);
+        expect(text === null || text === void 0 ? void 0 : text.chunks.join('')).toMatch(/ideas\/spark\.md/);
+        expect(text === null || text === void 0 ? void 0 : text.chunks.join('')).not.toMatch(/spec\.guml/);
+    });
+    it('filters docs by prefix when path given', async () => {
+        const docs = makeDocs({ listDocuments: vi.fn(async () => sampleDocs) });
+        const { ctx, pushed } = makeCtx(docs);
+        await lsVerb.run(ctx, ['notes/ideas']);
+        const text = pushed.find((e) => e.kind === 'text');
+        expect(text === null || text === void 0 ? void 0 : text.chunks.join('')).toMatch(/spark\.md/);
+        expect(text === null || text === void 0 ? void 0 : text.chunks.join('')).not.toMatch(/draft\.md/);
+    });
+    it('emits a status when shard has no docs', async () => {
+        const docs = makeDocs({ listDocuments: vi.fn(async () => sampleDocs) });
+        const { ctx, pushed } = makeCtx(docs);
+        await lsVerb.run(ctx, ['empty-shard']);
+        const status = pushed.find((e) => e.kind === 'status' && e.level === 'info');
+        expect(status).toBeDefined();
+    });
+});

package/dist/shell-shard/verbs/mkdir.d.ts

@@ -0,0 +1,2 @@
+import type { Verb } from '../../verbs/types';
+export declare const mkdirVerb: Verb;

package/dist/shell-shard/verbs/mkdir.js

@@ -0,0 +1,30 @@
+import { parseScopePath } from './scope-parse';
+export const mkdirVerb = {
+    name: 'mkdir',
+    summary: 'Create a folder. Usage: mkdir <shardId>/<folder>',
+    programmatic: true,
+    async run(ctx, args) {
+        const ts = Date.now();
+        if (!ctx.docs) {
+            ctx.scrollback.push({ kind: 'status', text: 'mkdir: document capability not available', level: 'error', ts });
+            return;
+        }
+        if (!args[0]) {
+            ctx.scrollback.push({ kind: 'status', text: 'usage: mkdir <shardId>/<folder>', level: 'error', ts });
+            return;
+        }
+        if (!ctx.docs.writeTo) {
+            ctx.scrollback.push({ kind: 'status', text: 'mkdir: write permission not granted', level: 'error', ts });
+            return;
+        }
+        const parsed = parseScopePath(args[0]);
+        if (!parsed || !parsed.path) {
+            ctx.scrollback.push({ kind: 'status', text: `mkdir: invalid path '${args[0]}'`, level: 'error', ts });
+            return;
+        }
+        // Materialise the folder with a sentinel file; backends treat paths as flat.
+        const keepPath = parsed.path.replace(/\/$/, '') + '/.keep';
+        await ctx.docs.writeTo(parsed.shardId, keepPath, '');
+        ctx.scrollback.push({ kind: 'status', text: `mkdir: created ${args[0]}`, level: 'info', ts });
+    },
+};

package/dist/shell-shard/verbs/mkdir.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shell-shard/verbs/mkdir.test.js

@@ -0,0 +1,48 @@
+import { describe, it, expect, vi } from 'vitest';
+import { mkdirVerb } from './mkdir';
+function makeDocs(overrides = {}) {
+    return Object.assign({ listDocuments: vi.fn(async () => []), listShards: vi.fn(async () => []), watchDocuments: vi.fn(() => () => { }), writeTo: vi.fn(async () => { }) }, overrides);
+}
+function makeCtx(docs) {
+    const pushed = [];
+    const ctx = {
+        sh3: {},
+        scrollback: { push: (e) => pushed.push(e) },
+        session: {},
+        cwd: '/',
+        fs: {},
+        docs,
+        dispatch: async () => { },
+    };
+    return { ctx, pushed };
+}
+describe('mkdir verb', () => {
+    it('emits error when docs capability missing', async () => {
+        const { ctx, pushed } = makeCtx(undefined);
+        await mkdirVerb.run(ctx, ['notes/ideas']);
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err).toBeDefined();
+    });
+    it('emits usage error when no args', async () => {
+        const { ctx, pushed } = makeCtx(makeDocs());
+        await mkdirVerb.run(ctx, []);
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err.text).toMatch(/usage/i);
+    });
+    it('creates a folder via writeTo', async () => {
+        const writeTo = vi.fn(async () => { });
+        const docs = makeDocs({ writeTo });
+        const { ctx, pushed } = makeCtx(docs);
+        await mkdirVerb.run(ctx, ['notes/ideas']);
+        expect(writeTo).toHaveBeenCalledWith('notes', 'ideas/.keep', '');
+        const ok = pushed.find((e) => e.kind === 'status' && e.level === 'info');
+        expect(ok).toBeDefined();
+    });
+    it('emits error when writeTo not available', async () => {
+        const docs = makeDocs({ writeTo: undefined });
+        const { ctx, pushed } = makeCtx(docs);
+        await mkdirVerb.run(ctx, ['notes/ideas']);
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err).toBeDefined();
+    });
+});

package/dist/shell-shard/verbs/mv.d.ts

@@ -0,0 +1,2 @@
+import type { Verb } from '../../verbs/types';
+export declare const mvVerb: Verb;

package/dist/shell-shard/verbs/mv.js

@@ -0,0 +1,33 @@
+import { parseScopePath } from './scope-parse';
+export const mvVerb = {
+    name: 'mv',
+    summary: 'Rename a document within a shard. Usage: mv <shardId>/<old> <shardId>/<new>',
+    programmatic: true,
+    async run(ctx, args) {
+        const ts = Date.now();
+        if (!ctx.docs) {
+            ctx.scrollback.push({ kind: 'status', text: 'mv: document capability not available', level: 'error', ts });
+            return;
+        }
+        if (args.length < 2) {
+            ctx.scrollback.push({ kind: 'status', text: 'usage: mv <shardId>/<old> <shardId>/<new>', level: 'error', ts });
+            return;
+        }
+        if (!ctx.docs.renameFrom) {
+            ctx.scrollback.push({ kind: 'status', text: 'mv: write permission not granted', level: 'error', ts });
+            return;
+        }
+        const src = parseScopePath(args[0]);
+        const dst = parseScopePath(args[1]);
+        if (!(src === null || src === void 0 ? void 0 : src.path) || !(dst === null || dst === void 0 ? void 0 : dst.path)) {
+            ctx.scrollback.push({ kind: 'status', text: 'mv: invalid path', level: 'error', ts });
+            return;
+        }
+        if (src.shardId !== dst.shardId) {
+            ctx.scrollback.push({ kind: 'status', text: 'mv: src and dst must be in the same shard (use xfer for cross-scope moves)', level: 'error', ts });
+            return;
+        }
+        await ctx.docs.renameFrom(src.shardId, src.path, dst.path);
+        ctx.scrollback.push({ kind: 'status', text: `mv: renamed ${args[0]} → ${args[1]}`, level: 'info', ts });
+    },
+};

package/dist/shell-shard/verbs/mv.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shell-shard/verbs/mv.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect, vi } from 'vitest';
+import { mvVerb } from './mv';
+function makeDocs(overrides = {}) {
+    return Object.assign({ listDocuments: vi.fn(async () => []), listShards: vi.fn(async () => []), watchDocuments: vi.fn(() => () => { }), renameFrom: vi.fn(async () => { }) }, overrides);
+}
+function makeCtx(docs) {
+    const pushed = [];
+    const ctx = {
+        sh3: {},
+        scrollback: { push: (e) => pushed.push(e) },
+        session: {},
+        cwd: '/',
+        fs: {},
+        docs,
+        dispatch: async () => { },
+    };
+    return { ctx, pushed };
+}
+describe('mv verb', () => {
+    it('emits error when docs capability missing', async () => {
+        const { ctx, pushed } = makeCtx(undefined);
+        await mvVerb.run(ctx, ['notes/old.md', 'notes/new.md']);
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err).toBeDefined();
+    });
+    it('emits usage error when fewer than two args', async () => {
+        const { ctx, pushed } = makeCtx(makeDocs());
+        await mvVerb.run(ctx, ['notes/old.md']);
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err.text).toMatch(/usage/i);
+    });
+    it('renames a document within the same shard', async () => {
+        const renameFrom = vi.fn(async () => { });
+        const docs = makeDocs({ renameFrom });
+        const { ctx, pushed } = makeCtx(docs);
+        await mvVerb.run(ctx, ['notes/old.md', 'notes/new.md']);
+        expect(renameFrom).toHaveBeenCalledWith('notes', 'old.md', 'new.md');
+        const ok = pushed.find((e) => e.kind === 'status' && e.level === 'info');
+        expect(ok).toBeDefined();
+    });
+    it('emits error when src and dst are in different shards', async () => {
+        const { ctx, pushed } = makeCtx(makeDocs());
+        await mvVerb.run(ctx, ['notes/old.md', 'design/new.md']);
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err).toBeDefined();
+        expect(err.text).toMatch(/same shard/i);
+    });
+    it('emits error when renameFrom not available', async () => {
+        const docs = makeDocs({ renameFrom: undefined });
+        const { ctx, pushed } = makeCtx(docs);
+        await mvVerb.run(ctx, ['notes/old.md', 'notes/new.md']);
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err).toBeDefined();
+    });
+});

package/dist/shell-shard/verbs/rm.d.ts

@@ -0,0 +1,2 @@
+import type { Verb } from '../../verbs/types';
+export declare const rmVerb: Verb;

package/dist/shell-shard/verbs/rm.js

@@ -0,0 +1,28 @@
+import { parseScopePath } from './scope-parse';
+export const rmVerb = {
+    name: 'rm',
+    summary: 'Delete a document. Usage: rm <shardId>/<path>',
+    programmatic: true,
+    async run(ctx, args) {
+        const ts = Date.now();
+        if (!ctx.docs) {
+            ctx.scrollback.push({ kind: 'status', text: 'rm: document capability not available', level: 'error', ts });
+            return;
+        }
+        if (!args[0]) {
+            ctx.scrollback.push({ kind: 'status', text: 'usage: rm <shardId>/<path>', level: 'error', ts });
+            return;
+        }
+        if (!ctx.docs.deleteFrom) {
+            ctx.scrollback.push({ kind: 'status', text: 'rm: write permission not granted', level: 'error', ts });
+            return;
+        }
+        const parsed = parseScopePath(args[0]);
+        if (!parsed || !parsed.path) {
+            ctx.scrollback.push({ kind: 'status', text: `rm: invalid path '${args[0]}'`, level: 'error', ts });
+            return;
+        }
+        await ctx.docs.deleteFrom(parsed.shardId, parsed.path);
+        ctx.scrollback.push({ kind: 'status', text: `rm: deleted ${args[0]}`, level: 'info', ts });
+    },
+};

package/dist/shell-shard/verbs/rm.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shell-shard/verbs/rm.test.js

@@ -0,0 +1,47 @@
+import { describe, it, expect, vi } from 'vitest';
+import { rmVerb } from './rm';
+function makeDocs(overrides = {}) {
+    return Object.assign({ listDocuments: vi.fn(async () => []), listShards: vi.fn(async () => []), watchDocuments: vi.fn(() => () => { }), deleteFrom: vi.fn(async () => { }) }, overrides);
+}
+function makeCtx(docs) {
+    const pushed = [];
+    const ctx = {
+        sh3: {},
+        scrollback: { push: (e) => pushed.push(e) },
+        session: {},
+        cwd: '/',
+        fs: {},
+        docs,
+        dispatch: async () => { },
+    };
+    return { ctx, pushed };
+}
+describe('rm verb', () => {
+    it('emits error when docs capability missing', async () => {
+        const { ctx, pushed } = makeCtx(undefined);
+        await rmVerb.run(ctx, ['notes/draft.md']);
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err).toBeDefined();
+    });
+    it('emits usage error when no args', async () => {
+        const { ctx, pushed } = makeCtx(makeDocs());
+        await rmVerb.run(ctx, []);
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err.text).toMatch(/usage/i);
+    });
+    it('deletes a document', async () => {
+        const docs = makeDocs({ deleteFrom: vi.fn(async () => { }) });
+        const { ctx, pushed } = makeCtx(docs);
+        await rmVerb.run(ctx, ['notes/draft.md']);
+        expect(docs.deleteFrom).toHaveBeenCalledWith('notes', 'draft.md');
+        const ok = pushed.find((e) => e.kind === 'status' && e.level === 'info');
+        expect(ok).toBeDefined();
+    });
+    it('emits error when deleteFrom not available on capability', async () => {
+        const docs = makeDocs({ deleteFrom: undefined });
+        const { ctx, pushed } = makeCtx(docs);
+        await rmVerb.run(ctx, ['notes/draft.md']);
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err).toBeDefined();
+    });
+});

package/dist/shell-shard/verbs/scope-parse.d.ts

@@ -0,0 +1,7 @@
+export interface ParsedScopePath {
+    scope: string | null;
+    shardId: string;
+    path: string;
+}
+export declare function parseScopePath(raw: string): ParsedScopePath | null;
+export declare function resolveScope(alias: string | null, activeId: string, personalId: string): string;

package/dist/shell-shard/verbs/scope-parse.js

@@ -0,0 +1,33 @@
+export function parseScopePath(raw) {
+    if (!raw)
+        return null;
+    let scope = null;
+    let rest = raw;
+    const colonIdx = raw.indexOf(':');
+    if (colonIdx > 0) {
+        const prefix = raw.slice(0, colonIdx);
+        if (prefix === '@me' || prefix.startsWith('@project-')) {
+            scope = prefix;
+            rest = raw.slice(colonIdx + 1);
+        }
+    }
+    if (!rest)
+        return null;
+    const slashIdx = rest.indexOf('/');
+    if (slashIdx < 0) {
+        return { scope, shardId: rest, path: '' };
+    }
+    const shardId = rest.slice(0, slashIdx);
+    if (!shardId)
+        return null;
+    return { scope, shardId, path: rest.slice(slashIdx + 1) };
+}
+export function resolveScope(alias, activeId, personalId) {
+    if (alias === null)
+        return activeId;
+    if (alias === '@me')
+        return personalId;
+    if (alias.startsWith('@project-'))
+        return alias.slice('@project-'.length);
+    throw new Error(`Unknown scope alias: ${alias}`);
+}

package/dist/shell-shard/verbs/scope-parse.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shell-shard/verbs/scope-parse.test.js

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { parseScopePath, resolveScope } from './scope-parse';
+describe('parseScopePath', () => {
+    it('parses a bare shard/path', () => {
+        expect(parseScopePath('notes/foo/bar.md')).toEqual({
+            scope: null,
+            shardId: 'notes',
+            path: 'foo/bar.md',
+        });
+    });
+    it('parses a shard root (no slash)', () => {
+        expect(parseScopePath('notes')).toEqual({
+            scope: null,
+            shardId: 'notes',
+            path: '',
+        });
+    });
+    it('parses @me: prefix', () => {
+        expect(parseScopePath('@me:notes/draft.md')).toEqual({
+            scope: '@me',
+            shardId: 'notes',
+            path: 'draft.md',
+        });
+    });
+    it('parses @project-slug: prefix', () => {
+        expect(parseScopePath('@project-acme:design/spec.md')).toEqual({
+            scope: '@project-acme',
+            shardId: 'design',
+            path: 'spec.md',
+        });
+    });
+    it('parses @project-compound-slug: prefix', () => {
+        expect(parseScopePath('@project-notes-v2:shard/path.md')).toEqual({
+            scope: '@project-notes-v2',
+            shardId: 'shard',
+            path: 'path.md',
+        });
+    });
+    it('parses @me: with shard root only', () => {
+        expect(parseScopePath('@me:notes')).toEqual({
+            scope: '@me',
+            shardId: 'notes',
+            path: '',
+        });
+    });
+    it('returns null for empty string', () => {
+        expect(parseScopePath('')).toBeNull();
+    });
+    it('returns null when scope prefix has no shard', () => {
+        expect(parseScopePath('@me:')).toBeNull();
+    });
+    it('treats unknown @-prefix as part of shard name (no scope)', () => {
+        // @unknown is not @me or @project-*, so no scope stripping
+        const result = parseScopePath('@unknown:shard/path');
+        expect(result === null || result === void 0 ? void 0 : result.scope).toBeNull();
+    });
+});
+describe('resolveScope', () => {
+    const active = 'proj-tenant';
+    const personal = 'user-tenant';
+    it('returns active scope for null alias', () => {
+        expect(resolveScope(null, active, personal)).toBe(active);
+    });
+    it('returns personal id for @me', () => {
+        expect(resolveScope('@me', active, personal)).toBe(personal);
+    });
+    it('strips @project- prefix to get project tenant id', () => {
+        expect(resolveScope('@project-acme', active, personal)).toBe('acme');
+    });
+    it('handles multi-segment project slug', () => {
+        expect(resolveScope('@project-notes-v2', active, personal)).toBe('notes-v2');
+    });
+    it('throws for unknown alias', () => {
+        expect(() => resolveScope('@unknown', active, personal)).toThrow();
+    });
+});

package/dist/shell-shard/verbs/xfer.d.ts

@@ -0,0 +1,2 @@
+import type { Verb } from '../../verbs/types';
+export declare const xferVerb: Verb;

package/dist/shell-shard/verbs/xfer.js

@@ -0,0 +1,101 @@
+import { parseScopePath, resolveScope } from './scope-parse';
+export const xferVerb = {
+    name: 'xfer',
+    summary: [
+        'Transfer docs across scopes. Usage: xfer [-R] [-C] <src> <dst>',
+        '  Scopes: @me | @project-<slug>  (e.g. @project-acme:notes/draft.md)',
+        '  -R  recursive (src is a folder prefix)',
+        '  -C  copy only, do not delete source',
+    ].join('\n'),
+    programmatic: true,
+    async run(ctx, args) {
+        const ts = Date.now();
+        if (!ctx.docs) {
+            ctx.scrollback.push({ kind: 'status', text: 'xfer: document capability not available', level: 'error', ts });
+            return;
+        }
+        const scope = ctx.sh3.getActiveScope();
+        if (!scope.isProject) {
+            ctx.scrollback.push({ kind: 'status', text: 'xfer: only available when a project scope is active', level: 'error', ts });
+            return;
+        }
+        // Parse flags
+        let recursive = false;
+        let copy = false;
+        const positional = [];
+        for (const a of args) {
+            if (a === '-R') {
+                recursive = true;
+                continue;
+            }
+            if (a === '-C') {
+                copy = true;
+                continue;
+            }
+            positional.push(a);
+        }
+        if (positional.length < 2) {
+            ctx.scrollback.push({ kind: 'status', text: 'usage: xfer [-R] [-C] <src> <dst>', level: 'error', ts });
+            return;
+        }
+        if (!ctx.docs.transferToScope) {
+            ctx.scrollback.push({ kind: 'status', text: 'xfer: write permission not granted', level: 'error', ts });
+            return;
+        }
+        const srcParsed = parseScopePath(positional[0]);
+        const dstParsed = parseScopePath(positional[1]);
+        if (!srcParsed || !dstParsed) {
+            ctx.scrollback.push({ kind: 'status', text: 'xfer: invalid path', level: 'error', ts });
+            return;
+        }
+        let srcTenant;
+        let dstTenant;
+        try {
+            srcTenant = resolveScope(srcParsed.scope, scope.id, scope.personalId);
+            dstTenant = resolveScope(dstParsed.scope, scope.id, scope.personalId);
+        }
+        catch (e) {
+            ctx.scrollback.push({ kind: 'status', text: `xfer: ${e.message}`, level: 'error', ts });
+            return;
+        }
+        // transferToScope always reads from the active tenant; reject if src doesn't match.
+        if (srcTenant !== scope.id) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: 'xfer: source must be the active project scope in v1 — switch to the source scope first',
+                level: 'error',
+                ts,
+            });
+            return;
+        }
+        const opts = { delete: !copy, targetShardId: dstParsed.shardId };
+        if (!recursive) {
+            if (!srcParsed.path) {
+                ctx.scrollback.push({ kind: 'status', text: 'xfer: path required (use -R for folder recursion)', level: 'error', ts });
+                return;
+            }
+            await ctx.docs.transferToScope(srcParsed.shardId, srcParsed.path, dstTenant, opts);
+            const verb = copy ? 'copied' : 'moved';
+            ctx.scrollback.push({ kind: 'status', text: `xfer: ${verb} ${positional[0]} → ${positional[1]}`, level: 'info', ts });
+            return;
+        }
+        // Recursive: list all docs in srcTenant matching the prefix
+        // transferToScope uses getTenantId() (active scope) — to read from srcTenant
+        // we rely on the src scope being the active tenant or the capability seeing it.
+        // For v1 we use listDocuments (active tenant) and filter by shard + prefix.
+        const prefix = srcParsed.path;
+        const allDocs = await ctx.docs.listDocuments();
+        const matching = allDocs.filter((d) => d.shardId === srcParsed.shardId && (!prefix || d.path.startsWith(prefix)));
+        if (matching.length === 0) {
+            ctx.scrollback.push({ kind: 'status', text: `xfer: no documents found under ${positional[0]}`, level: 'info', ts });
+            return;
+        }
+        let count = 0;
+        for (const doc of matching) {
+            await ctx.docs.transferToScope(doc.shardId, doc.path, dstTenant, opts);
+            count++;
+        }
+        const verb = copy ? 'copied' : 'moved';
+        ctx.scrollback.push({ kind: 'status', text: `xfer: ${verb} ${count} document${count !== 1 ? 's' : ''}`, level: 'info', ts });
+    },
+};

package/dist/shell-shard/verbs/xfer.test.d.ts

@@ -0,0 +1 @@
+export {};