sh3-core 0.20.1 → 0.20.3

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,87 @@
+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. @me:notes/draft.md, @project-acme:notes/draft.md)',
+        '  Either side may be @me or @project-<slug>; bare paths resolve to the active scope.',
+        '  -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;
+        }
+        if (!ctx.docs.transferBetweenScopes) {
+            ctx.scrollback.push({ kind: 'status', text: 'xfer: write permission not granted', level: 'error', ts });
+            return;
+        }
+        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;
+        }
+        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;
+        }
+        const scope = ctx.sh3.getActiveScope();
+        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;
+        }
+        const moveOpts = { delete: !copy };
+        if (!recursive) {
+            if (!srcParsed.path) {
+                ctx.scrollback.push({ kind: 'status', text: 'xfer: path required (use -R for folder recursion)', level: 'error', ts });
+                return;
+            }
+            if (srcTenant === dstTenant && srcParsed.shardId === dstParsed.shardId && srcParsed.path === dstParsed.path) {
+                ctx.scrollback.push({ kind: 'status', text: 'xfer: source and destination are the same', level: 'error', ts });
+                return;
+            }
+            await ctx.docs.transferBetweenScopes(srcTenant, srcParsed.shardId, srcParsed.path, dstTenant, dstParsed.shardId, dstParsed.path, moveOpts);
+            const verb = copy ? 'copied' : 'moved';
+            ctx.scrollback.push({ kind: 'status', text: `xfer: ${verb} ${positional[0]} → ${positional[1]}`, level: 'info', ts });
+            return;
+        }
+        const prefix = srcParsed.path;
+        const allDocs = await ctx.docs.listDocumentsIn(srcTenant);
+        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.transferBetweenScopes(srcTenant, doc.shardId, doc.path, dstTenant, dstParsed.shardId, doc.path, moveOpts);
+            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 {};

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

@@ -0,0 +1,107 @@
+import { describe, it, expect, vi } from 'vitest';
+import { xferVerb } from './xfer';
+function makeDocs(overrides = {}) {
+    return Object.assign({ listDocuments: vi.fn(async () => []), listShards: vi.fn(async () => []), watchDocuments: vi.fn(() => () => { }), transferToScope: vi.fn(async () => { }), listDocumentsIn: vi.fn(async () => []), transferBetweenScopes: vi.fn(async () => { }) }, overrides);
+}
+function makeSh3(scope) {
+    return {
+        getActiveScope: () => scope,
+        listProjects: () => [],
+    };
+}
+function makeCtx(docs, sh3) {
+    const pushed = [];
+    const ctx = {
+        sh3: sh3 !== null && sh3 !== void 0 ? sh3 : {},
+        scrollback: { push: (e) => pushed.push(e) },
+        session: {},
+        cwd: '/',
+        fs: {},
+        docs,
+        dispatch: async () => { },
+    };
+    return { ctx, pushed };
+}
+const projectScope = { id: 'proj-abc', isProject: true, personalId: 'user-me' };
+const personalScope = { id: 'user-me', isProject: false, personalId: 'user-me' };
+describe('xfer verb', () => {
+    it('emits error when docs capability missing', async () => {
+        const sh3 = makeSh3(projectScope);
+        const { ctx, pushed } = makeCtx(undefined, sh3);
+        await xferVerb.run(ctx, ['@project-proj-abc:notes/draft.md', '@me:notes/draft.md']);
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err).toBeDefined();
+    });
+    it('works from personal (non-project) scope', async () => {
+        const transferBetweenScopes = vi.fn(async () => { });
+        const docs = makeDocs({ transferBetweenScopes });
+        const sh3 = makeSh3(personalScope);
+        const { ctx, pushed } = makeCtx(docs, sh3);
+        await xferVerb.run(ctx, ['@me:notes/draft.md', '@project-proj-abc:notes/draft.md']);
+        expect(transferBetweenScopes).toHaveBeenCalledWith('user-me', 'notes', 'draft.md', 'proj-abc', 'notes', 'draft.md', expect.objectContaining({ delete: true }));
+        const ok = pushed.find((e) => e.kind === 'status' && e.level === 'info');
+        expect(ok).toBeDefined();
+    });
+    it('emits usage error when fewer than two args', async () => {
+        const sh3 = makeSh3(projectScope);
+        const { ctx, pushed } = makeCtx(makeDocs(), sh3);
+        await xferVerb.run(ctx, ['notes/draft.md']);
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err.text).toMatch(/usage/i);
+    });
+    it('moves a doc from project to personal scope', async () => {
+        const transferBetweenScopes = vi.fn(async () => { });
+        const docs = makeDocs({ transferBetweenScopes });
+        const sh3 = makeSh3(projectScope);
+        const { ctx, pushed } = makeCtx(docs, sh3);
+        await xferVerb.run(ctx, ['@project-proj-abc:notes/draft.md', '@me:notes/draft.md']);
+        expect(transferBetweenScopes).toHaveBeenCalledWith('proj-abc', 'notes', 'draft.md', 'user-me', 'notes', 'draft.md', expect.objectContaining({ delete: true }));
+        const ok = pushed.find((e) => e.kind === 'status' && e.level === 'info');
+        expect(ok).toBeDefined();
+    });
+    it('-C flag copies without deleting source', async () => {
+        const transferBetweenScopes = vi.fn(async () => { });
+        const docs = makeDocs({ transferBetweenScopes });
+        const sh3 = makeSh3(projectScope);
+        const { ctx } = makeCtx(docs, sh3);
+        await xferVerb.run(ctx, ['-C', '@project-proj-abc:notes/draft.md', '@me:notes/draft.md']);
+        expect(transferBetweenScopes).toHaveBeenCalledWith('proj-abc', 'notes', 'draft.md', 'user-me', 'notes', 'draft.md', expect.objectContaining({ delete: false }));
+    });
+    it('allows @me as source when project scope is active', async () => {
+        const transferBetweenScopes = vi.fn(async () => { });
+        const docs = makeDocs({ transferBetweenScopes });
+        const sh3 = makeSh3(projectScope);
+        const { ctx, pushed } = makeCtx(docs, sh3);
+        await xferVerb.run(ctx, ['@me:notes/draft.md', '@project-proj-abc:notes/draft.md']);
+        expect(transferBetweenScopes).toHaveBeenCalledWith('user-me', 'notes', 'draft.md', 'proj-abc', 'notes', 'draft.md', expect.objectContaining({ delete: true }));
+        const ok = pushed.find((e) => e.kind === 'status' && e.level === 'info');
+        expect(ok).toBeDefined();
+    });
+    it('emits error when source and destination are identical', async () => {
+        const transferBetweenScopes = vi.fn(async () => { });
+        const docs = makeDocs({ transferBetweenScopes });
+        const sh3 = makeSh3(projectScope);
+        const { ctx, pushed } = makeCtx(docs, sh3);
+        await xferVerb.run(ctx, ['@project-proj-abc:notes/draft.md', '@project-proj-abc:notes/draft.md']);
+        expect(transferBetweenScopes).not.toHaveBeenCalled();
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err.text).toMatch(/same/i);
+    });
+    it('-R flag recurses over all docs matching src prefix', async () => {
+        const transferBetweenScopes = vi.fn(async () => { });
+        const allDocs = [
+            { shardId: 'notes', path: 'ideas/a.md', size: 1, lastModified: 0 },
+            { shardId: 'notes', path: 'ideas/b.md', size: 1, lastModified: 0 },
+            { shardId: 'notes', path: 'other.md', size: 1, lastModified: 0 },
+        ];
+        const docs = makeDocs({
+            transferBetweenScopes,
+            listDocumentsIn: vi.fn(async () => allDocs),
+        });
+        const sh3 = makeSh3(projectScope);
+        const { ctx } = makeCtx(docs, sh3);
+        await xferVerb.run(ctx, ['-R', '@project-proj-abc:notes/ideas', '@me:notes/ideas']);
+        expect(transferBetweenScopes).toHaveBeenCalledTimes(2);
+        expect(transferBetweenScopes).toHaveBeenCalledWith('proj-abc', 'notes', 'ideas/a.md', 'user-me', 'notes', 'ideas/a.md', expect.objectContaining({ delete: true }));
+    });
+});

package/dist/verbs/types.d.ts

@@ -5,6 +5,7 @@ import type { TreeRootRef } from '../layout/types';
 import type { DispatchToTerminalResult } from '../shell-shard/dispatch-to-terminal';
 import type { ActionDescriptor } from '../actions/types';
 import type { FieldsApi } from '../fields/types';
+import type { BrowseCapability } from '../documents/browse';
 export interface Sh3Api {
     listApps(): Array<{
         id: string;
@@ -158,6 +159,21 @@ export interface Sh3Api {
      * Controllable-field surface — see fields/types.ts:FieldsApi for shape.
      */
     fields: FieldsApi;
+    /**
+     * Active scope identity. `id` is the current tenant (project or personal).
+     * `personalId` is always the user's base tenant regardless of active project.
+     * `isProject` is true when a project scope is currently active.
+     */
+    getActiveScope(): {
+        id: string;
+        isProject: boolean;
+        personalId: string;
+    };
+    /** List projects visible to the current user. */
+    listProjects(): Array<{
+        id: string;
+        name: string;
+    }>;
 }
 export type { DispatchToTerminalResult } from '../shell-shard/dispatch-to-terminal';
 export interface VerbContext {
@@ -166,6 +182,8 @@ export interface VerbContext {
     session: SessionClient;
     cwd: string;
     fs: TenantFsClient;
+    /** Document zone browse capability. Present when shell-shard has documents:browse permission. */
+    docs?: BrowseCapability;
     /** Invoke another registered verb programmatically (used by rich-entry clicks). */
     dispatch(line: string): Promise<void>;
     /**

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export declare const VERSION = "0.20.1";
+export declare const VERSION = "0.20.3";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export const VERSION = '0.20.1';
+export const VERSION = '0.20.3';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh3-core",
-  "version": "0.20.1",
+  "version": "0.20.3",
   "type": "module",
   "files": [
     "dist"