sh3-core 0.24.0 → 0.25.1

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/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.24.0";
+export declare const VERSION = "0.25.1";

package/dist/version.js

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

package/package.json

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