sh3-core 0.20.1 → 0.20.2

package/dist/primitives/widgets/_DocumentBrowser.svelte.test.js

@@ -0,0 +1,277 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, fireEvent, screen } from '@testing-library/svelte';
+import DocumentBrowser from './_DocumentBrowser.svelte';
+function makeHandle() {
+    return {
+        mkdir: vi.fn().mockResolvedValue(undefined),
+        rmdir: vi.fn().mockResolvedValue(undefined),
+        renameFolder: vi.fn().mockResolvedValue(undefined),
+        rename: vi.fn().mockResolvedValue(undefined),
+        delete: vi.fn().mockResolvedValue(undefined),
+    };
+}
+const sampleDocs = [
+    { shardId: 'sh1', path: 'a.md', size: 100, lastModified: 0 },
+    { shardId: 'sh1', path: 'sub/b.md', size: 200, lastModified: 0 },
+];
+function baseProps(extra = {}) {
+    return Object.assign({ mode: 'open', docs: sampleDocs, onCommit: vi.fn(), onCancel: vi.fn(), close: vi.fn() }, extra);
+}
+describe('_DocumentBrowser toolbar visibility', () => {
+    it('toolbar is hidden at the shard-list view (shardId === null)', async () => {
+        render(DocumentBrowser, { props: baseProps({ handle: makeHandle() }) });
+        expect(document.querySelector('.sh3-doc-browser__toolbar')).toBeNull();
+    });
+    it('toolbar is visible when inside a shard and handle is provided', async () => {
+        const { container } = render(DocumentBrowser, { props: baseProps({ handle: makeHandle() }) });
+        await fireEvent.click(screen.getByText('sh1'));
+        expect(container.querySelector('.sh3-doc-browser__toolbar')).not.toBeNull();
+    });
+    it('toolbar is hidden when readOnlyShard returns true', async () => {
+        const { container } = render(DocumentBrowser, {
+            props: baseProps({ handle: makeHandle(), readOnlyShard: () => true }),
+        });
+        await fireEvent.click(screen.getByText('sh1'));
+        expect(container.querySelector('.sh3-doc-browser__toolbar')).toBeNull();
+    });
+    it('toolbar is hidden when no handle is provided', async () => {
+        const { container } = render(DocumentBrowser, { props: baseProps() });
+        await fireEvent.click(screen.getByText('sh1'));
+        expect(container.querySelector('.sh3-doc-browser__toolbar')).toBeNull();
+    });
+});
+describe('_DocumentBrowser navigation', () => {
+    it('clicking a shard navigates into it and shows its contents', async () => {
+        render(DocumentBrowser, { props: baseProps() });
+        expect(screen.getByText('sh1')).not.toBeNull();
+        await fireEvent.click(screen.getByText('sh1'));
+        expect(screen.getByText('a.md')).not.toBeNull();
+        expect(screen.getByText('sub')).not.toBeNull();
+    });
+    it('double-clicking a file commits it in open mode', async () => {
+        const onCommit = vi.fn();
+        const close = vi.fn();
+        render(DocumentBrowser, { props: baseProps({ onCommit, close }) });
+        await fireEvent.click(screen.getByText('sh1'));
+        await fireEvent.dblClick(screen.getByText('a.md'));
+        expect(onCommit).toHaveBeenCalledWith({ shardId: 'sh1', path: 'a.md', kind: 'file' });
+        expect(close).toHaveBeenCalled();
+    });
+    it('double-clicking a folder navigates into it', async () => {
+        render(DocumentBrowser, { props: baseProps() });
+        await fireEvent.click(screen.getByText('sh1'));
+        await fireEvent.dblClick(screen.getByText('sub'));
+        expect(screen.getByText('b.md')).not.toBeNull();
+    });
+    it('clicking a folder with selectable=folder selects it, not navigates', async () => {
+        const onCommit = vi.fn();
+        render(DocumentBrowser, {
+            props: baseProps({ onCommit, selectable: 'folder' }),
+        });
+        // Use dblClick to navigate into sh1 (dblClick always navigates)
+        await fireEvent.dblClick(screen.getByText('sh1'));
+        // Now inside sh1: clicking sub should select it, not navigate
+        await fireEvent.click(screen.getByText('sub'));
+        expect(screen.queryByText('b.md')).toBeNull(); // not navigated
+        // Open button should be enabled since a folder is selected
+        const openBtn = screen.getByText('Open');
+        expect(openBtn.disabled).toBe(false);
+    });
+});
+describe('_DocumentBrowser commit and cancel', () => {
+    it('Open button is disabled when nothing is selected', async () => {
+        render(DocumentBrowser, { props: baseProps() });
+        await fireEvent.click(screen.getByText('sh1'));
+        const openBtn = screen.getByText('Open');
+        expect(openBtn.disabled).toBe(true);
+    });
+    it('Open button is enabled when a file is selected', async () => {
+        render(DocumentBrowser, { props: baseProps() });
+        await fireEvent.click(screen.getByText('sh1'));
+        await fireEvent.click(screen.getByText('a.md'));
+        const openBtn = screen.getByText('Open');
+        expect(openBtn.disabled).toBe(false);
+    });
+    it('clicking Open commits the selected file', async () => {
+        const onCommit = vi.fn();
+        const close = vi.fn();
+        render(DocumentBrowser, { props: baseProps({ onCommit, close }) });
+        await fireEvent.click(screen.getByText('sh1'));
+        await fireEvent.click(screen.getByText('a.md'));
+        await fireEvent.click(screen.getByText('Open'));
+        expect(onCommit).toHaveBeenCalledWith({ shardId: 'sh1', path: 'a.md', kind: 'file' });
+        expect(close).toHaveBeenCalled();
+    });
+    it('Cancel calls onCancel and close', async () => {
+        const onCancel = vi.fn();
+        const close = vi.fn();
+        render(DocumentBrowser, { props: baseProps({ onCancel, close }) });
+        await fireEvent.click(screen.getByText('Cancel'));
+        expect(onCancel).toHaveBeenCalled();
+        expect(close).toHaveBeenCalled();
+    });
+});
+describe('_DocumentBrowser new folder', () => {
+    beforeEach(() => { vi.clearAllMocks(); });
+    it('clicking New folder shows an inline editable row', async () => {
+        const handle = makeHandle();
+        const { container } = render(DocumentBrowser, { props: baseProps({ handle }) });
+        await fireEvent.click(screen.getByText('sh1'));
+        const newFolderBtn = container.querySelector('[title="New folder"]');
+        await fireEvent.click(newFolderBtn);
+        const input = container.querySelector('.sh3-doc-browser__rename-input');
+        expect(input).not.toBeNull();
+    });
+    it('entering a name and pressing Enter calls handle.mkdir', async () => {
+        const handle = makeHandle();
+        const { container } = render(DocumentBrowser, { props: baseProps({ handle }) });
+        await fireEvent.click(screen.getByText('sh1'));
+        const newFolderBtn = container.querySelector('[title="New folder"]');
+        await fireEvent.click(newFolderBtn);
+        const input = container.querySelector('.sh3-doc-browser__rename-input');
+        await fireEvent.input(input, { target: { value: 'newdir' } });
+        await fireEvent.keyDown(input, { key: 'Enter' });
+        expect(handle.mkdir).toHaveBeenCalledWith('sh1', 'newdir');
+    });
+    it('Esc cancels new folder without calling mkdir', async () => {
+        const handle = makeHandle();
+        const { container } = render(DocumentBrowser, { props: baseProps({ handle }) });
+        await fireEvent.click(screen.getByText('sh1'));
+        const newFolderBtn = container.querySelector('[title="New folder"]');
+        await fireEvent.click(newFolderBtn);
+        const input = container.querySelector('.sh3-doc-browser__rename-input');
+        await fireEvent.keyDown(input, { key: 'Escape' });
+        expect(handle.mkdir).not.toHaveBeenCalled();
+        expect(container.querySelector('.sh3-doc-browser__rename-input')).toBeNull();
+    });
+    it('duplicate name shows error and does not call mkdir', async () => {
+        const handle = makeHandle();
+        const { container } = render(DocumentBrowser, { props: baseProps({ handle }) });
+        await fireEvent.click(screen.getByText('sh1'));
+        const newFolderBtn = container.querySelector('[title="New folder"]');
+        await fireEvent.click(newFolderBtn);
+        const input = container.querySelector('.sh3-doc-browser__rename-input');
+        // 'sub' already exists as a folder from sampleDocs
+        await fireEvent.input(input, { target: { value: 'sub' } });
+        await fireEvent.keyDown(input, { key: 'Enter' });
+        expect(handle.mkdir).not.toHaveBeenCalled();
+        const errorEl = container.querySelector('.sh3-doc-browser__toolbar-error');
+        expect(errorEl === null || errorEl === void 0 ? void 0 : errorEl.textContent).toMatch(/already exists/);
+    });
+});
+describe('_DocumentBrowser rename', () => {
+    beforeEach(() => { vi.clearAllMocks(); });
+    it('clicking Rename while a file is selected shows inline input', async () => {
+        const handle = makeHandle();
+        const { container } = render(DocumentBrowser, { props: baseProps({ handle }) });
+        await fireEvent.click(screen.getByText('sh1'));
+        await fireEvent.click(screen.getByText('a.md'));
+        const renameBtn = container.querySelector('[title="Rename"]');
+        await fireEvent.click(renameBtn);
+        const input = container.querySelector('.sh3-doc-browser__rename-input');
+        expect(input).not.toBeNull();
+        expect(input.value).toBe('a.md');
+    });
+    it('confirming rename calls handle.rename', async () => {
+        const handle = makeHandle();
+        const { container } = render(DocumentBrowser, { props: baseProps({ handle }) });
+        await fireEvent.click(screen.getByText('sh1'));
+        await fireEvent.click(screen.getByText('a.md'));
+        const renameBtn = container.querySelector('[title="Rename"]');
+        await fireEvent.click(renameBtn);
+        const input = container.querySelector('.sh3-doc-browser__rename-input');
+        await fireEvent.input(input, { target: { value: 'renamed.md' } });
+        await fireEvent.keyDown(input, { key: 'Enter' });
+        expect(handle.rename).toHaveBeenCalledWith('sh1', 'a.md', 'renamed.md');
+    });
+});
+describe('_DocumentBrowser delete', () => {
+    beforeEach(() => { vi.clearAllMocks(); });
+    it('clicking Delete while a file is selected shows confirm overlay', async () => {
+        const handle = makeHandle();
+        const { container } = render(DocumentBrowser, { props: baseProps({ handle }) });
+        await fireEvent.click(screen.getByText('sh1'));
+        await fireEvent.click(screen.getByText('a.md'));
+        const deleteBtn = container.querySelector('[title="Delete"]');
+        await fireEvent.click(deleteBtn);
+        expect(container.querySelector('.sh3-confirm-delete')).not.toBeNull();
+    });
+    it('confirming delete calls handle.delete', async () => {
+        const handle = makeHandle();
+        const { container } = render(DocumentBrowser, { props: baseProps({ handle }) });
+        await fireEvent.click(screen.getByText('sh1'));
+        await fireEvent.click(screen.getByText('a.md'));
+        const deleteBtn = container.querySelector('[title="Delete"]');
+        await fireEvent.click(deleteBtn);
+        const confirmBtn = container.querySelector('.sh3-confirm-delete__btn--danger');
+        await fireEvent.click(confirmBtn);
+        expect(handle.delete).toHaveBeenCalledWith('sh1', 'a.md');
+    });
+    it('cancelling delete hides the overlay without calling delete', async () => {
+        const handle = makeHandle();
+        const { container } = render(DocumentBrowser, { props: baseProps({ handle }) });
+        await fireEvent.click(screen.getByText('sh1'));
+        await fireEvent.click(screen.getByText('a.md'));
+        const deleteBtn = container.querySelector('[title="Delete"]');
+        await fireEvent.click(deleteBtn);
+        const cancelBtn = container.querySelector('.sh3-confirm-delete__btn:not(.sh3-confirm-delete__btn--danger)');
+        await fireEvent.click(cancelBtn);
+        expect(handle.delete).not.toHaveBeenCalled();
+        expect(container.querySelector('.sh3-confirm-delete')).toBeNull();
+    });
+});
+describe('_DocumentBrowser cut and paste', () => {
+    beforeEach(() => { vi.clearAllMocks(); });
+    it('Paste button is disabled when clipboard is empty', async () => {
+        const handle = makeHandle();
+        const { container } = render(DocumentBrowser, { props: baseProps({ handle }) });
+        await fireEvent.click(screen.getByText('sh1'));
+        const pasteBtn = container.querySelector('[title="Paste"]');
+        expect(pasteBtn.disabled).toBe(true);
+    });
+    it('Cut then Paste calls handle.rename with new path', async () => {
+        const handle = makeHandle();
+        const { container } = render(DocumentBrowser, { props: baseProps({ handle }) });
+        await fireEvent.click(screen.getByText('sh1'));
+        await fireEvent.click(screen.getByText('a.md'));
+        const cutBtn = container.querySelector('[title="Cut"]');
+        await fireEvent.click(cutBtn);
+        // Navigate into sub folder (dblclick)
+        await fireEvent.dblClick(screen.getByText('sub'));
+        const pasteBtn = container.querySelector('[title="Paste"]');
+        expect(pasteBtn.disabled).toBe(false);
+        await fireEvent.click(pasteBtn);
+        expect(handle.rename).toHaveBeenCalledWith('sh1', 'a.md', 'sub/a.md');
+    });
+});
+describe('_DocumentBrowser save mode', () => {
+    it('shows filename input when inside a shard in save mode', async () => {
+        const { container } = render(DocumentBrowser, {
+            props: Object.assign(Object.assign({}, baseProps()), { mode: 'save' }),
+        });
+        await fireEvent.click(screen.getByText('sh1'));
+        expect(container.querySelector('.sh3-doc-browser__save-input')).not.toBeNull();
+    });
+    it('clicking a file in save mode populates the filename field', async () => {
+        const { container } = render(DocumentBrowser, {
+            props: Object.assign(Object.assign({}, baseProps()), { mode: 'save' }),
+        });
+        await fireEvent.click(screen.getByText('sh1'));
+        await fireEvent.click(screen.getByText('a.md'));
+        const input = container.querySelector('.sh3-doc-browser__save-input');
+        expect(input.value).toBe('a.md');
+    });
+    it('Save commits the typed path', async () => {
+        const onCommit = vi.fn();
+        const close = vi.fn();
+        const { container } = render(DocumentBrowser, {
+            props: Object.assign(Object.assign({}, baseProps({ onCommit, close })), { mode: 'save' }),
+        });
+        await fireEvent.click(screen.getByText('sh1'));
+        const input = container.querySelector('.sh3-doc-browser__save-input');
+        await fireEvent.input(input, { target: { value: 'report.txt' } });
+        await fireEvent.click(screen.getByText('Save'));
+        expect(onCommit).toHaveBeenCalledWith('sh1/report.txt');
+        expect(close).toHaveBeenCalled();
+    });
+});

package/dist/primitives/widgets/_FolderConfirmDelete.svelte

@@ -0,0 +1,57 @@
+<script lang="ts">
+  let {
+    item,
+    childCount,
+    onConfirm,
+    onCancel,
+  }: {
+    item: { kind: 'file' | 'folder'; name: string };
+    childCount: number;
+    onConfirm: () => void;
+    onCancel: () => void;
+  } = $props();
+</script>
+
+<div class="sh3-confirm-delete">
+  <div class="sh3-confirm-delete__title">
+    {#if item.kind === 'file'}
+      Delete "{item.name}"?
+    {:else if childCount === 0}
+      Delete folder "{item.name}"?
+    {:else}
+      Delete folder "{item.name}" and {childCount} item{childCount === 1 ? '' : 's'}?
+    {/if}
+  </div>
+  <div class="sh3-confirm-delete__buttons">
+    <button type="button" class="sh3-confirm-delete__btn" onclick={onCancel}>Cancel</button>
+    <button type="button" class="sh3-confirm-delete__btn sh3-confirm-delete__btn--danger" onclick={onConfirm}>Delete</button>
+  </div>
+</div>
+
+<style>
+  .sh3-confirm-delete {
+    padding: 12px 16px;
+    min-width: 240px;
+    color: var(--sh3-fg);
+    font-size: 0.8125rem;
+  }
+  .sh3-confirm-delete__title { font-size: 0.875rem; margin-bottom: 12px; }
+  .sh3-confirm-delete__buttons { display: flex; justify-content: flex-end; gap: 8px; }
+  .sh3-confirm-delete__btn {
+    display: inline-flex; align-items: center;
+    height: 26px; padding: 0 12px;
+    border: 1px solid var(--sh3-border);
+    border-radius: var(--sh3-radius-sm);
+    background: var(--sh3-bg-elevated);
+    color: var(--sh3-fg);
+    font: inherit; font-size: 0.75rem;
+    cursor: pointer;
+  }
+  .sh3-confirm-delete__btn:hover { background: var(--sh3-bg); }
+  .sh3-confirm-delete__btn--danger {
+    background: var(--sh3-error);
+    color: var(--sh3-fg-on-error);
+    border-color: var(--sh3-error);
+  }
+  .sh3-confirm-delete__btn--danger:hover { filter: brightness(1.1); }
+</style>

package/dist/primitives/widgets/_FolderConfirmDelete.svelte.d.ts

@@ -0,0 +1,12 @@
+type $$ComponentProps = {
+    item: {
+        kind: 'file' | 'folder';
+        name: string;
+    };
+    childCount: number;
+    onConfirm: () => void;
+    onCancel: () => void;
+};
+declare const FolderConfirmDelete: import("svelte").Component<$$ComponentProps, {}, "">;
+type FolderConfirmDelete = ReturnType<typeof FolderConfirmDelete>;
+export default FolderConfirmDelete;

package/dist/sh3Api/headless.js

@@ -31,6 +31,8 @@ import { listFields as listFieldsImpl, getField as getFieldImpl, setField as set
 import { attachDecoration as attachDecorationImpl } from '../fields/decoration';
 import { onChange as onContributionsChange } from '../contributions';
 import { FIELD_POINT_ID, WALKER_SHARD_ID } from '../fields/types';
+import { getActiveScopeId, getPersonalScopeId } from '../documents/config';
+import { projectsState } from '../projects-shard/projectsShard.svelte';
 const KNOWN_ZONES = ['ephemeral', 'session', 'workspace', 'user'];
 function collectTabEntries(node) {
     if (node.type === 'tabs') {
@@ -317,6 +319,14 @@ export function makeSh3Api(opts) {
             return listViewsImpl();
         },
         fields,
+        getActiveScope() {
+            const id = getActiveScopeId();
+            const personalId = getPersonalScopeId();
+            return { id, isProject: id !== personalId, personalId };
+        },
+        listProjects() {
+            return projectsState.projects.map((p) => ({ id: p.id, name: p.name }));
+        },
     };
 }
 /** @deprecated Renamed to makeSh3Api(opts?). Kept for one minor cycle. */

package/dist/shards/activate.svelte.js

@@ -19,7 +19,7 @@
 import { sh3 } from '../sh3Runtime.svelte';
 import { registerView, unregisterView, registerVerb as fwRegisterVerb, unregisterVerb as fwUnregisterVerb } from './registry';
 import { makeSh3Api } from '../sh3Api/headless';
-import { createDocumentHandle, getTenantId, getDocumentBackend } from '../documents';
+import { createDocumentHandle, getTenantId, getDocumentBackend, getActiveScopeId } from '../documents';
 import { fetchEnvState, putEnvState } from '../env/client';
 import { getEnvServerUrl } from '../env/index';
 import { apiFetch } from '../transport/apiFetch';
@@ -179,7 +179,7 @@ export async function activateShard(id, opts) {
             }
         },
         documents: (options) => {
-            const handle = createDocumentHandle(getTenantId(), id, getDocumentBackend(), options);
+            const handle = createDocumentHandle(getActiveScopeId(), id, getDocumentBackend(), options);
             entry.cleanupFns.push(() => handle.dispose());
             return handle;
         },

package/dist/shell-shard/Terminal.svelte

@@ -28,6 +28,7 @@
   import BusySlot from './toolbar/slots/BusySlot.svelte';
   import { registerTerminalView, mintTerminalId, type TerminalHandle } from './terminal-registry';
   import { makeDispatchToTerminal } from './dispatch-to-terminal';
+  import type { BrowseCapability } from '../documents/browse';
 
   interface Props {
     shell: Sh3Api;
@@ -35,8 +36,9 @@
     userId: string;
     role: ShellRole;
     contributions: ContributionsApi;
+    docs?: BrowseCapability;
   }
-  let { shell, wsUrl, userId, role, contributions }: Props = $props();
+  let { shell, wsUrl, userId, role, contributions, docs }: Props = $props();
 
   // Per-mode buffer map. Each ModeBuffer bundles a Scrollback + history +
   // locked flag and is materialized lazily on first switch into that mode.
@@ -250,6 +252,7 @@
     session,
     sh3: shellWithModes,
     fs,
+    docs,
     cwd: () => session.cwd,
     busy: acquireBusy,
     customMode: (id: string) => contributedModes.find((d) => d.id === id) ?? null,

package/dist/shell-shard/Terminal.svelte.d.ts

@@ -1,12 +1,14 @@
 import { type Sh3Api } from './registry';
 import type { ShellRole } from './modes/types';
 import type { ContributionsApi } from '../contributions/types';
+import type { BrowseCapability } from '../documents/browse';
 interface Props {
     shell: Sh3Api;
     wsUrl: string;
     userId: string;
     role: ShellRole;
     contributions: ContributionsApi;
+    docs?: BrowseCapability;
 }
 declare const Terminal: import("svelte").Component<Props, {}, "">;
 type Terminal = ReturnType<typeof Terminal>;

package/dist/shell-shard/dispatch.d.ts

@@ -4,6 +4,7 @@ import type { TenantFsClient } from './tenant-fs-client';
 import type { ModeBuffer } from './mode-buffer.svelte';
 import type { ShellMode, ShellRole } from './modes/types';
 import type { ShellModeDescriptor } from './contract';
+import type { BrowseCapability } from '../documents/browse';
 export interface DispatchDeps {
     mode: () => ShellMode;
     /** Current shell role — used by invoke() role-gating. */
@@ -18,6 +19,7 @@ export interface DispatchDeps {
     session: SessionClient;
     sh3: Sh3Api;
     fs: TenantFsClient;
+    docs?: BrowseCapability;
     cwd: () => string;
     /**
      * Acquire a busy indicator. Returns a clear handle. Calling clear()

package/dist/shell-shard/dispatch.js

@@ -39,6 +39,7 @@ export function makeDispatch(deps) {
                 cwd: deps.cwd(),
                 dispatch,
                 fs: deps.fs,
+                docs: deps.docs,
             }, resolution.args);
             return;
         }
@@ -107,6 +108,7 @@ export function makeDispatch(deps) {
                     cwd: deps.cwd(),
                     dispatch,
                     fs: deps.fs,
+                    docs: deps.docs,
                 }, resolution.args);
             }
             catch (err) {

package/dist/shell-shard/manifest.js

@@ -1,5 +1,6 @@
 import { VERSION } from '../version';
 import { PERMISSION_STATE_MANAGE } from '../state/types';
+import { PERMISSION_DOCUMENTS_BROWSE, PERMISSION_DOCUMENTS_READ, PERMISSION_DOCUMENTS_WRITE, } from '../documents/types';
 export const manifest = {
     id: 'shell',
     label: 'Sh3',
@@ -9,5 +10,10 @@ export const manifest = {
     // and is statically mounted at sh3-server boot. The existing contract in
     // sh3-core/src/shards/types.ts documents that framework-shipped shards do
     // not use this field.
-    permissions: [PERMISSION_STATE_MANAGE],
+    permissions: [
+        PERMISSION_STATE_MANAGE,
+        PERMISSION_DOCUMENTS_BROWSE,
+        PERMISSION_DOCUMENTS_READ,
+        PERMISSION_DOCUMENTS_WRITE,
+    ],
 };

package/dist/shell-shard/shellShard.svelte.js

@@ -64,7 +64,7 @@ export const shellShard = {
                 const role = isAdmin() ? 'admin' : 'user';
                 const instance = mount(Terminal, {
                     target: container,
-                    props: { shell, wsUrl, userId, role, contributions: ctx.contributions },
+                    props: { shell, wsUrl, userId, role, contributions: ctx.contributions, docs: ctx.browse },
                 });
                 return {
                     unmount() {

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

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

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

@@ -0,0 +1,35 @@
+import { parseScopePath } from './scope-parse';
+export const catVerb = {
+    name: 'cat',
+    summary: 'Print document content. Usage: cat <shardId>/<path>',
+    programmatic: true,
+    async run(ctx, args) {
+        const ts = Date.now();
+        if (!ctx.docs) {
+            ctx.scrollback.push({ kind: 'status', text: 'cat: document capability not available', level: 'error', ts });
+            return;
+        }
+        if (!args[0]) {
+            ctx.scrollback.push({ kind: 'status', text: 'usage: cat <shardId>/<path>', level: 'error', ts });
+            return;
+        }
+        const parsed = parseScopePath(args[0]);
+        if (!parsed || !parsed.path) {
+            ctx.scrollback.push({ kind: 'status', text: `cat: invalid path '${args[0]}'`, level: 'error', ts });
+            return;
+        }
+        if (!ctx.docs.readFrom) {
+            ctx.scrollback.push({ kind: 'status', text: 'cat: read permission not granted', level: 'error', ts });
+            return;
+        }
+        const content = await ctx.docs.readFrom(parsed.shardId, parsed.path);
+        if (content === null) {
+            ctx.scrollback.push({ kind: 'status', text: `cat: not found: ${args[0]}`, level: 'error', ts });
+            return;
+        }
+        const text = content instanceof ArrayBuffer
+            ? `<binary ${content.byteLength}b>`
+            : content;
+        ctx.scrollback.push({ kind: 'text', stream: 'stdout', chunks: [text], ts });
+    },
+};

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

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

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

@@ -0,0 +1,49 @@
+import { describe, it, expect, vi } from 'vitest';
+import { catVerb } from './cat';
+function makeDocs(overrides = {}) {
+    return Object.assign({ listDocuments: vi.fn(async () => []), listShards: vi.fn(async () => []), watchDocuments: vi.fn(() => () => { }), readFrom: vi.fn(async () => null) }, 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('cat verb', () => {
+    it('emits error when docs capability missing', async () => {
+        const { ctx, pushed } = makeCtx(undefined);
+        await catVerb.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 catVerb.run(ctx, []);
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err).toBeDefined();
+        expect(err.text).toMatch(/usage/i);
+    });
+    it('outputs document content', async () => {
+        const docs = makeDocs({ readFrom: vi.fn(async () => 'hello world') });
+        const { ctx, pushed } = makeCtx(docs);
+        await catVerb.run(ctx, ['notes/draft.md']);
+        expect(docs.readFrom).toHaveBeenCalledWith('notes', 'draft.md');
+        const text = pushed.find((e) => e.kind === 'text');
+        expect(text === null || text === void 0 ? void 0 : text.chunks.join('')).toContain('hello world');
+    });
+    it('emits error when document not found', async () => {
+        const docs = makeDocs({ readFrom: vi.fn(async () => null) });
+        const { ctx, pushed } = makeCtx(docs);
+        await catVerb.run(ctx, ['notes/missing.md']);
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err).toBeDefined();
+        expect(err.text).toMatch(/not found/i);
+    });
+});

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

@@ -12,6 +12,12 @@ import { viewsVerb, openVerb, closeVerb, popoutVerb, dockVerb } from './views';
 import { zonesVerb, zoneVerb } from './zones';
 import { envVerb } from './env';
 import { resetVerb } from './reset';
+import { lsVerb } from './ls';
+import { catVerb } from './cat';
+import { rmVerb } from './rm';
+import { mkdirVerb } from './mkdir';
+import { mvVerb } from './mv';
+import { xferVerb } from './xfer';
 export function registerV1Verbs(ctx) {
     ctx.registerVerb(makeHelpVerb());
     ctx.registerVerb(clearVerb);
@@ -29,4 +35,10 @@ export function registerV1Verbs(ctx) {
     ctx.registerVerb(zoneVerb);
     ctx.registerVerb(envVerb);
     ctx.registerVerb(resetVerb);
+    ctx.registerVerb(lsVerb);
+    ctx.registerVerb(catVerb);
+    ctx.registerVerb(rmVerb);
+    ctx.registerVerb(mkdirVerb);
+    ctx.registerVerb(mvVerb);
+    ctx.registerVerb(xferVerb);
 }

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

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