sh3-core 0.23.2 → 0.25.0

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

@@ -1,4 +1,38 @@
 import { parseScopePath, resolveScope } from './scope-parse';
+// ---------------------------------------------------------------------------
+// Path helpers
+//
+// xfer follows cp-style semantics for the destination:
+//   - dst path ending with `/` (or empty) is a directory; the file is placed
+//     inside with the source's filename (or, for -R, with the source-relative
+//     path rebased under the dst directory).
+//   - dst path without trailing slash is treated literally.
+// ---------------------------------------------------------------------------
+function basename(p) {
+    const i = p.lastIndexOf('/');
+    return i >= 0 ? p.slice(i + 1) : p;
+}
+/** Compose a final dst path from a (possibly-directory) dst dir plus a relative segment. */
+function joinDst(dstDir, relative) {
+    if (!dstDir)
+        return relative;
+    if (dstDir.endsWith('/'))
+        return dstDir + relative;
+    return `${dstDir}/${relative}`;
+}
+/**
+ * Strip a folder prefix off a doc path, returning the remainder. For the
+ * single-file case (doc.path equals prefix), returns the filename. The
+ * caller's filter guarantees doc.path is either exactly `prefix` or starts
+ * with `prefix + '/'`, so this never produces a stray leading slash.
+ */
+function rebaseFromPrefix(prefix, docPath) {
+    if (!prefix)
+        return docPath;
+    if (docPath === prefix)
+        return basename(docPath);
+    return docPath.slice(prefix.length + 1); // skip prefix and the separating '/'
+}
 export const xferVerb = {
     name: 'xfer',
     summary: [
@@ -7,6 +41,7 @@ export const xferVerb = {
         '  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',
+        '  Trailing `/` on dst means "into directory" (cp-style); without it dst is a literal path.',
     ].join('\n'),
     programmatic: true,
     async run(ctx, args) {
@@ -60,25 +95,52 @@ export const xferVerb = {
                 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) {
+            // cp-style: trailing slash (or empty path) means "into this directory" —
+            // append the source filename so the file lands inside instead of trying
+            // to overwrite the directory itself.
+            const dstIsDir = !dstParsed.path || dstParsed.path.endsWith('/');
+            const dstFinalPath = dstIsDir
+                ? joinDst(dstParsed.path, basename(srcParsed.path))
+                : dstParsed.path;
+            if (srcTenant === dstTenant && srcParsed.shardId === dstParsed.shardId && srcParsed.path === dstFinalPath) {
                 ctx.scrollback.push({ kind: 'status', text: 'xfer: source and destination are the same', level: 'error', ts });
                 return;
             }
-            await ctx.sh3.docs.transferBetweenScopes(srcTenant, srcParsed.shardId, srcParsed.path, dstTenant, dstParsed.shardId, dstParsed.path, moveOpts);
+            await ctx.sh3.docs.transferBetweenScopes(srcTenant, srcParsed.shardId, srcParsed.path, dstTenant, dstParsed.shardId, dstFinalPath, 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.sh3.docs.listDocumentsIn(srcTenant);
-        const matching = allDocs.filter((d) => d.shardId === srcParsed.shardId && (!prefix || d.path.startsWith(prefix)));
+        // Folder-boundary filter: when `prefix` is set, a doc matches only if its
+        // path equals the prefix (single-file case) or sits inside the prefix
+        // folder (`prefix + '/'` ...). Plain `startsWith(prefix)` would also
+        // match sibling files whose names happen to share the prefix string
+        // (e.g. prefix `notes` matching `notesheet.md`).
+        const matching = allDocs.filter((d) => {
+            if (d.shardId !== srcParsed.shardId)
+                return false;
+            if (!prefix)
+                return true;
+            if (d.path === prefix)
+                return true;
+            return 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.sh3.docs.transferBetweenScopes(srcTenant, doc.shardId, doc.path, dstTenant, dstParsed.shardId, doc.path, moveOpts);
+            // Per-doc dst: rebase the doc's path relative to the src prefix, then
+            // place it under the dst directory. Without this the dst directory is
+            // ignored and the file lands at its source path in dst shard, which
+            // (a) silently misplaces the file and (b) blows up on mounts where
+            // `mounts/<unknown-segment>/...` fails to resolve to a real mount.
+            const relative = rebaseFromPrefix(prefix, doc.path);
+            const dstFinalPath = joinDst(dstParsed.path, relative);
+            await ctx.sh3.docs.transferBetweenScopes(srcTenant, doc.shardId, doc.path, dstTenant, dstParsed.shardId, dstFinalPath, moveOpts);
             count++;
         }
         const verb = copy ? 'copied' : 'moved';

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

@@ -104,4 +104,78 @@ describe('xfer verb', () => {
         expect(transferBetweenScopes).toHaveBeenCalledTimes(2);
         expect(transferBetweenScopes).toHaveBeenCalledWith('proj-abc', 'notes', 'ideas/a.md', 'user-me', 'notes', 'ideas/a.md', expect.objectContaining({ delete: true }));
     });
+    // ---------------------------------------------------------------------------
+    // Bug repro — xfer -R discards dst directory; dst with trailing slash should
+    // preserve it; substring-prefix filter false-matches.
+    // ---------------------------------------------------------------------------
+    it('-R preserves dst directory when transferring into a different folder', async () => {
+        // User's exact scenario: a single file under svg-designer goes into a
+        // mount subdirectory. Previously dst.path was discarded and the file
+        // landed at `mounts/sh3_dirt.svg`, which the mount resolver interpreted
+        // as `mountId=sh3_dirt.svg` → 500.
+        const transferBetweenScopes = vi.fn(async () => { });
+        const allDocs = [
+            { shardId: 'svg-designer', path: 'sh3_dirt.svg', size: 1, lastModified: 0 },
+        ];
+        const docs = makeDocs({
+            transferBetweenScopes,
+            listDocumentsIn: vi.fn(async () => allDocs),
+        });
+        const sh3 = makeSh3(personalScope);
+        const { ctx } = makeCtx(docs, sh3);
+        await xferVerb.run(ctx, ['-R', '-C', '@me:svg-designer/sh3_dirt.svg', 'mounts/square-survivor/']);
+        expect(transferBetweenScopes).toHaveBeenCalledTimes(1);
+        expect(transferBetweenScopes).toHaveBeenCalledWith('user-me', 'svg-designer', 'sh3_dirt.svg', 'user-me', 'mounts', 'square-survivor/sh3_dirt.svg', expect.objectContaining({ delete: false }));
+    });
+    it('-R rebases doc paths under a folder prefix into the dst directory', async () => {
+        const transferBetweenScopes = vi.fn(async () => { });
+        const allDocs = [
+            { shardId: 'notes', path: 'ideas/a.md', size: 1, lastModified: 0 },
+            { shardId: 'notes', path: 'ideas/sub/b.md', size: 1, lastModified: 0 },
+        ];
+        const docs = makeDocs({
+            transferBetweenScopes,
+            listDocumentsIn: vi.fn(async () => allDocs),
+        });
+        const sh3 = makeSh3(personalScope);
+        const { ctx } = makeCtx(docs, sh3);
+        await xferVerb.run(ctx, ['-R', '@me:notes/ideas', '@me:notes/archived/']);
+        expect(transferBetweenScopes).toHaveBeenCalledTimes(2);
+        expect(transferBetweenScopes).toHaveBeenCalledWith('user-me', 'notes', 'ideas/a.md', 'user-me', 'notes', 'archived/a.md', expect.anything());
+        expect(transferBetweenScopes).toHaveBeenCalledWith('user-me', 'notes', 'ideas/sub/b.md', 'user-me', 'notes', 'archived/sub/b.md', expect.anything());
+    });
+    it('-R filter respects folder boundary — does not match substring prefixes', async () => {
+        const transferBetweenScopes = vi.fn(async () => { });
+        const allDocs = [
+            { shardId: 'notes', path: 'notes/draft.md', size: 1, lastModified: 0 },
+            { shardId: 'notes', path: 'notesheet.md', size: 1, lastModified: 0 },
+        ];
+        const docs = makeDocs({
+            transferBetweenScopes,
+            listDocumentsIn: vi.fn(async () => allDocs),
+        });
+        const sh3 = makeSh3(personalScope);
+        const { ctx } = makeCtx(docs, sh3);
+        await xferVerb.run(ctx, ['-R', '@me:notes/notes', '@me:notes/archived/']);
+        // Only notes/draft.md matches the folder prefix `notes`. notesheet.md
+        // shares the substring but is a sibling file, not a child.
+        expect(transferBetweenScopes).toHaveBeenCalledTimes(1);
+        expect(transferBetweenScopes).toHaveBeenCalledWith('user-me', 'notes', 'notes/draft.md', 'user-me', 'notes', 'archived/draft.md', expect.anything());
+    });
+    it('non-recursive: trailing-slash dst appends source filename', async () => {
+        const transferBetweenScopes = vi.fn(async () => { });
+        const docs = makeDocs({ transferBetweenScopes });
+        const sh3 = makeSh3(personalScope);
+        const { ctx } = makeCtx(docs, sh3);
+        await xferVerb.run(ctx, ['@me:notes/foo.md', '@me:notes/archived/']);
+        expect(transferBetweenScopes).toHaveBeenCalledWith('user-me', 'notes', 'foo.md', 'user-me', 'notes', 'archived/foo.md', expect.anything());
+    });
+    it('non-recursive: literal dst path is used verbatim (no trailing slash)', async () => {
+        const transferBetweenScopes = vi.fn(async () => { });
+        const docs = makeDocs({ transferBetweenScopes });
+        const sh3 = makeSh3(personalScope);
+        const { ctx } = makeCtx(docs, sh3);
+        await xferVerb.run(ctx, ['@me:notes/foo.md', '@me:notes/archived/renamed.md']);
+        expect(transferBetweenScopes).toHaveBeenCalledWith('user-me', 'notes', 'foo.md', 'user-me', 'notes', 'archived/renamed.md', expect.anything());
+    });
 });

package/dist/transport/apiFetch.js

@@ -14,6 +14,7 @@
  * defensive pattern as `platform/index.ts`. Vite code-splits it
  * into a Tauri-only chunk that never loads in web builds.
  */
+import { getEnvServerUrl } from '../env/serverUrl';
 import { getAuthToken } from './authToken';
 let tauriFetch = null;
 let tauriProbed = false;
@@ -43,8 +44,25 @@ async function getTauriFetch() {
     }
     return tauriFetch;
 }
+// Resolve relative paths against the configured server URL so callers can
+// use bare `/api/...` paths and have them hit the configured sh3-server
+// regardless of the webview's origin. Mirrors ctx.fetch's resolveUrl —
+// absolute URLs pass through, relatives get prefixed when a serverUrl is
+// set. When no serverUrl is configured (e.g. early bootstrap, web builds
+// hosted same-origin), the path is left untouched so `fetch` falls back
+// to `window.location.origin` as before.
+function resolveApiUrl(url) {
+    if (url.startsWith('http://') || url.startsWith('https://'))
+        return url;
+    const base = getEnvServerUrl();
+    if (!base)
+        return url;
+    const sep = url.startsWith('/') ? '' : '/';
+    return `${base}${sep}${url}`;
+}
 export function apiFetch(url, init) {
     var _a;
+    const resolved = resolveApiUrl(url);
     // Inject Authorization: Bearer <session-token> if a session is active
     // and the caller didn't already supply one. Cookies don't survive the
     // cross-origin hop (SameSite=Lax + plugin-http has no cookie store),
@@ -62,11 +80,11 @@ export function apiFetch(url, init) {
     // call-timing assertions in tests still hold and web builds skip the
     // dynamic-import probe entirely.
     if (!inTauriRuntime()) {
-        return fetch(url, Object.assign({ credentials: 'include' }, finalInit));
+        return fetch(resolved, Object.assign({ credentials: 'include' }, finalInit));
     }
     return getTauriFetch().then((tf) => {
         if (tf)
-            return tf(url, finalInit);
-        return fetch(url, Object.assign({ credentials: 'include' }, finalInit));
+            return tf(resolved, finalInit);
+        return fetch(resolved, Object.assign({ credentials: 'include' }, finalInit));
     });
 }

package/dist/transport/apiFetch.test.js

@@ -34,4 +34,67 @@ describe('apiFetch', () => {
         const [, init] = calls[0];
         expect(init.credentials).toBe('omit');
     });
+    it('resolves relative paths against the configured serverUrl', async () => {
+        const calls = [];
+        globalThis.fetch = vi.fn(async (input) => {
+            calls.push(String(input));
+            return new Response('ok');
+        });
+        const { __setEnvServerUrl } = await import('../env/serverUrl');
+        __setEnvServerUrl('https://remote.example.com');
+        try {
+            const { apiFetch } = await import('./apiFetch');
+            await apiFetch('/api/admin/users');
+            expect(calls[0]).toBe('https://remote.example.com/api/admin/users');
+        }
+        finally {
+            __setEnvServerUrl('');
+        }
+    });
+    it('prepends a slash to bare relative paths when serverUrl is set', async () => {
+        const calls = [];
+        globalThis.fetch = vi.fn(async (input) => {
+            calls.push(String(input));
+            return new Response('ok');
+        });
+        const { __setEnvServerUrl } = await import('../env/serverUrl');
+        __setEnvServerUrl('https://remote.example.com');
+        try {
+            const { apiFetch } = await import('./apiFetch');
+            await apiFetch('api/admin/users');
+            expect(calls[0]).toBe('https://remote.example.com/api/admin/users');
+        }
+        finally {
+            __setEnvServerUrl('');
+        }
+    });
+    it('passes absolute URLs through unchanged regardless of serverUrl', async () => {
+        const calls = [];
+        globalThis.fetch = vi.fn(async (input) => {
+            calls.push(String(input));
+            return new Response('ok');
+        });
+        const { __setEnvServerUrl } = await import('../env/serverUrl');
+        __setEnvServerUrl('https://remote.example.com');
+        try {
+            const { apiFetch } = await import('./apiFetch');
+            await apiFetch('https://other.example.com/api/bar');
+            expect(calls[0]).toBe('https://other.example.com/api/bar');
+        }
+        finally {
+            __setEnvServerUrl('');
+        }
+    });
+    it('leaves relative paths alone when no serverUrl is configured', async () => {
+        const calls = [];
+        globalThis.fetch = vi.fn(async (input) => {
+            calls.push(String(input));
+            return new Response('ok');
+        });
+        const { __setEnvServerUrl } = await import('../env/serverUrl');
+        __setEnvServerUrl('');
+        const { apiFetch } = await import('./apiFetch');
+        await apiFetch('/api/admin/users');
+        expect(calls[0]).toBe('/api/admin/users');
+    });
 });

package/dist/verbs/types.d.ts

@@ -209,14 +209,14 @@ export interface VerbContext {
     signal?: AbortSignal;
 }
 /**
- * Portable JSON Schema subset accepted by sh3-core for `Verb.schema.input`.
- * Documented as the intersection of what Anthropic, OpenAI, and Gemini
- * tool-call APIs accept natively. sh3-core does NOT validate that the
- * actual schema stays within this subset — authors who reach for `oneOf`,
- * `$ref`, or other Draft 2020-12 features do so at their own portability
- * risk. The type is intentionally `unknown`-permissive on `properties`
- * and `items` so authors can express object/array shapes without
- * fighting the type system.
+ * Portable JSON Schema subset accepted by sh3-core for `Verb.schema.input`
+ * and `Verb.schema.output`. Documented as the intersection of what
+ * Anthropic, OpenAI, and Gemini tool-call APIs accept natively. sh3-core
+ * does NOT validate that the actual schema stays within this subset —
+ * authors who reach for `oneOf`, `$ref`, or other Draft 2020-12 features
+ * do so at their own portability risk. The type is intentionally
+ * `unknown`-permissive on `properties` and `items` so authors can express
+ * object/array shapes without fighting the type system.
  */
 export interface PortableJSONSchema {
     type?: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
@@ -229,14 +229,39 @@ export interface PortableJSONSchema {
     required?: string[];
     /** Item schema for `type: 'array'`. */
     items?: PortableJSONSchema;
+    /**
+     * JSON Schema `format` hint. sh3-core blesses one value:
+     *   - 'sh3-document' — runtime payload is an SH3 document handle
+     *     ({ shardId: string; path: string }). Combine with type: 'object'.
+     * Other `format` values pass through untouched (portability with
+     * JSON Schema validators and tool-call APIs is preserved).
+     */
+    format?: string;
 }
 /**
- * Optional schema attached to a verb. Today only `input` is consumed
- * (by sh3-ai's tool-call dispatcher); `output` is deferred until
- * sh3-editor's graph view materializes a real consumer.
+ * Optional schema attached to a verb. `input` is consumed by sh3-ai's
+ * tool-call dispatcher and by sh3-pipeline's verb-adapter. `output`
+ * describes the shape of the verb's return value (the `result` field
+ * of `Sh3Api.runVerb`'s Promise resolution) and is consumed by
+ * sh3-pipeline to derive output ports.
  */
 export interface VerbSchema {
     input: PortableJSONSchema;
+    /**
+     * Shape of the verb's return value. When omitted, callers treat the
+     * verb as side-effect-only and read the scrollback instead.
+     *
+     *   - {type:'object', properties:{…}} → result is an object whose
+     *     own properties match the schema. Each top-level property is
+     *     one logical output (one port for sh3-pipeline).
+     *   - any other type                  → result IS that value.
+     *
+     * Document outputs are declared as
+     *   { type: 'object', format: 'sh3-document',
+     *     properties: { shardId: {type:'string'}, path: {type:'string'} } }
+     * or inlined inside a parent object's properties.
+     */
+    output?: PortableJSONSchema;
 }
 export interface Verb {
     name: string;
@@ -271,7 +296,19 @@ export interface Verb {
      * whether to read it or fall back to `args[]`.
      */
     schema?: VerbSchema;
-    run(ctx: VerbContext, args: string[]): Promise<void>;
+    /**
+     * Returns the verb's structured result. The return value MUST match
+     * the shape declared by `schema.output` when both are present:
+     *   - schema.output {type:'object', properties:{…}} → return object with those keys
+     *   - schema.output primitive                       → return that primitive
+     *   - schema.output undefined                       → return value is ignored
+     *
+     * Verbs that don't declare schema.output may return undefined; the
+     * Sh3Api.runVerb resolution surfaces it as `result: undefined`.
+     * Existing verbs that returned Promise<void> remain assignable —
+     * `void` is a subtype of `unknown` for return-type widening.
+     */
+    run(ctx: VerbContext, args: string[]): Promise<unknown>;
 }
 export type Resolution = {
     kind: 'local';

package/dist/verbs/types.test.d.ts

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

package/dist/verbs/types.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expectTypeOf } from 'vitest';
+describe('VerbSchema with output', () => {
+    it('accepts output as PortableJSONSchema', () => {
+        const schema = {
+            input: { type: 'object', properties: { topic: { type: 'string' } } },
+            output: { type: 'object', properties: { answer: { type: 'string' } } },
+        };
+        expectTypeOf(schema.output).toEqualTypeOf();
+    });
+    it('accepts format on PortableJSONSchema', () => {
+        const docSchema = {
+            type: 'object',
+            format: 'sh3-document',
+            properties: {
+                shardId: { type: 'string' },
+                path: { type: 'string' },
+            },
+        };
+        expectTypeOf(docSchema.format).toEqualTypeOf();
+    });
+});
+describe('Verb.run return type', () => {
+    it('accepts a verb returning Promise<unknown>', () => {
+        const v = {
+            name: 'demo',
+            summary: 's',
+            async run() {
+                return { answer: 'ok' };
+            },
+        };
+        expectTypeOf(v.run).returns.toEqualTypeOf();
+    });
+    it('accepts a legacy verb returning Promise<void>', () => {
+        const v = {
+            name: 'legacy',
+            summary: 's',
+            async run() {
+                // returns nothing
+            },
+        };
+        expectTypeOf(v.run).returns.toEqualTypeOf();
+    });
+});

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

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