@pstdio/sdk 0.22.1 → 0.24.0

package/README.md

@@ -32,6 +32,32 @@ Page targets change location. Panel targets preserve it. Compound targets contai
 
 Use `qualifyRef(owner, ref)` in provider contract modules. Keep definitions local and pass qualified refs between extensions. For webviews, declare capabilities and call the typed `GuestHost`; `placement.close` closes the calling placement through the normal tab controller.
 
+## Dashboard URLs
+
+Use `serializePageUrl({ projectId, page, resource })` to return a dashboard link from a command. The page descriptor contains its `id`, qualified `ref`, and declared `path`; `resource` is optional. The workbench uses the same route and resource codec.
+
+Use `parsePageUrl({ url, projectId, pages })` to resolve a saved link against the expected project and allowed page descriptors. It accepts root-relative URLs and returns a page ID and optional resource, or `undefined` for an unsupported destination. It never fetches the URL. The caller still checks its supported resource kind and owner. A URL grants no access.
+
+Page and panel navigation targets remain the API for opening views and tabs.
+
+## Webview change subscriptions
+
+Use the typed client's `events.subscribe(event, listener)` to refetch after a command changes data:
+
+```ts
+const client = createWebviewClient<typeof commands>(host);
+const stop = client.events.subscribe(
+  { kind: "event", id: "notes.changed" },
+  () => void reloadNotes(),
+);
+// Dispose when the view unmounts.
+stop();
+```
+
+Local event refs use the client's extension owner: `{ kind: "event", id: "notes.changed" }` resolves to `<extensionId>.event.notes.changed`. Qualified event refs can name another extension in the same project. String IDs are already resolved and stay unchanged. Host-owned and command-lifecycle refs follow the runtime's rules through the shared `resolveEventReferenceId` helper. Commands emit events after committing their changes through `ctx.events.emit`.
+
+The host delivers only events matching the view's project. Projectless events reach global views only. Listeners also run when host sync connects or reconnects, so a mounted view can reconcile missed changes. Load current data when mounting, then subscribe; events are invalidations, not stored records or an exactly-once stream. Duplicate refetches must be safe. The subscription does not reload the webview document or grant new permissions.
+
 ## Package delivery
 
 Development and installed consumers both load built SDK entries. Repository development builds this package before starting the source CLI. Builds stage release files under `.publish` through the shared release script. Package verification installs those same staged artifacts into a temporary directory outside the monorepo and checks every entry point.

package/dist/api/index.js

@@ -13909,6 +13909,7 @@ var listExtensionConnectionsResponseSchema = exports_external.object({
 
 // ../pstdio-api-contracts/src/extensions/execute.ts
 var extensionResourceRefSchema = exports_external.object({
+  shorthand: exports_external.string().optional(),
   type: exports_external.string(),
   id: exports_external.string(),
   projectId: exports_external.string().optional(),
@@ -15458,9 +15459,11 @@ var resolveSessionIdResponseSchema = exports_external.object({
 });
 // ../pstdio-api-contracts/src/settings.ts
 var settingsSchema = exports_external.object({
+  notifications_enabled: exports_external.boolean(),
   max_concurrent_sessions: exports_external.number().int().min(1).nullable()
 });
 var updateSettingsInputSchema = exports_external.object({
+  notifications_enabled: exports_external.boolean().optional(),
   max_concurrent_sessions: exports_external.number().int().min(1).nullable().optional()
 }).strict().refine((value) => Object.keys(value).length > 0, { message: "Expected at least one setting" });
 // ../pstdio-api-contracts/src/skills.ts

package/dist/api.d.ts

@@ -93,6 +93,7 @@ declare const commandExecuteRequestSchema: z.ZodObject<{
     workspaceId: z.ZodOptional<z.ZodString>;
     params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     resource: z.ZodOptional<z.ZodObject<{
+        shorthand: z.ZodOptional<z.ZodString>;
         type: z.ZodString;
         id: z.ZodString;
         projectId: z.ZodOptional<z.ZodString>;
@@ -120,6 +121,7 @@ declare const commandExecuteRequestSchema: z.ZodObject<{
         mode: z.ZodOptional<z.ZodString>;
         projectId: z.ZodOptional<z.ZodString>;
         resource: z.ZodOptional<z.ZodObject<{
+            shorthand: z.ZodOptional<z.ZodString>;
             type: z.ZodString;
             id: z.ZodString;
             projectId: z.ZodOptional<z.ZodString>;
@@ -247,6 +249,7 @@ declare const createAutomationRunInputSchema: z.ZodObject<{
         workspaceId: z.ZodOptional<z.ZodString>;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         resource: z.ZodOptional<z.ZodObject<{
+            shorthand: z.ZodOptional<z.ZodString>;
             type: z.ZodString;
             id: z.ZodString;
             projectId: z.ZodOptional<z.ZodString>;
@@ -290,6 +293,7 @@ declare const createSessionInputSchema: z.ZodObject<{
     agent: z.ZodOptional<z.ZodString>;
     workspace_id: z.ZodOptional<z.ZodString>;
     anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        shorthand: z.ZodOptional<z.ZodString>;
         type: z.ZodString;
         id: z.ZodString;
         projectId: z.ZodOptional<z.ZodString>;
@@ -448,6 +452,7 @@ declare const extensionKeybindingRecordSchema: z.ZodObject<{
             id: z.ZodString;
         }, z.core.$strip>]>;
         resource: z.ZodOptional<z.ZodObject<{
+            shorthand: z.ZodOptional<z.ZodString>;
             type: z.ZodString;
             id: z.ZodString;
             projectId: z.ZodOptional<z.ZodString>;
@@ -491,6 +496,7 @@ declare const extensionKeybindingRecordSchema: z.ZodObject<{
                 id: z.ZodString;
             }, z.core.$strip>]>;
             resource: z.ZodOptional<z.ZodObject<{
+                shorthand: z.ZodOptional<z.ZodString>;
                 type: z.ZodString;
                 id: z.ZodString;
                 projectId: z.ZodOptional<z.ZodString>;
@@ -597,6 +603,7 @@ declare const extensionRecordSchema: z.ZodObject<{
 }, z.core.$strip>;
 
 declare const extensionResourceRefSchema: z.ZodObject<{
+    shorthand: z.ZodOptional<z.ZodString>;
     type: z.ZodString;
     id: z.ZodString;
     projectId: z.ZodOptional<z.ZodString>;
@@ -1318,6 +1325,7 @@ declare const resolveSessionIdResponseSchema: z.ZodObject<{
 export declare interface ResourceRef {
     type: string;
     id: string;
+    shorthand?: string;
     projectId?: string;
     label?: string;
     icon?: string;
@@ -1423,6 +1431,7 @@ declare const sessionConversationResponseSchema: z.ZodObject<{
         cwd: z.ZodNullable<z.ZodString>;
         params_json: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>>;
         anchors_json: z.ZodArray<z.ZodObject<{
+            shorthand: z.ZodOptional<z.ZodString>;
             type: z.ZodString;
             id: z.ZodString;
             projectId: z.ZodOptional<z.ZodString>;
@@ -1440,6 +1449,7 @@ declare const sessionConversationResponseSchema: z.ZodObject<{
 export declare type Settings = z.infer<typeof settingsSchema>;
 
 declare const settingsSchema: z.ZodObject<{
+    notifications_enabled: z.ZodBoolean;
     max_concurrent_sessions: z.ZodNullable<z.ZodNumber>;
 }, z.core.$strip>;
 
@@ -1513,6 +1523,7 @@ export declare interface UpdateNotificationInput {
 export declare type UpdateSettingsInput = z.infer<typeof updateSettingsInputSchema>;
 
 declare const updateSettingsInputSchema: z.ZodObject<{
+    notifications_enabled: z.ZodOptional<z.ZodBoolean>;
     max_concurrent_sessions: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strict>;
 
@@ -1855,6 +1866,7 @@ declare const workbenchExtensionMetadataSchema: z.ZodObject<{
                             id: z.ZodString;
                         }, z.core.$strip>]>;
                         resource: z.ZodOptional<z.ZodObject<{
+                            shorthand: z.ZodOptional<z.ZodString>;
                             type: z.ZodString;
                             id: z.ZodString;
                             projectId: z.ZodOptional<z.ZodString>;
@@ -1898,6 +1910,7 @@ declare const workbenchExtensionMetadataSchema: z.ZodObject<{
                                 id: z.ZodString;
                             }, z.core.$strip>]>;
                             resource: z.ZodOptional<z.ZodObject<{
+                                shorthand: z.ZodOptional<z.ZodString>;
                                 type: z.ZodString;
                                 id: z.ZodString;
                                 projectId: z.ZodOptional<z.ZodString>;
@@ -2369,6 +2382,7 @@ declare const workbenchExtensionMetadataSchema: z.ZodObject<{
                         id: z.ZodString;
                     }, z.core.$strip>]>;
                     resource: z.ZodOptional<z.ZodObject<{
+                        shorthand: z.ZodOptional<z.ZodString>;
                         type: z.ZodString;
                         id: z.ZodString;
                         projectId: z.ZodOptional<z.ZodString>;
@@ -2412,6 +2426,7 @@ declare const workbenchExtensionMetadataSchema: z.ZodObject<{
                             id: z.ZodString;
                         }, z.core.$strip>]>;
                         resource: z.ZodOptional<z.ZodObject<{
+                            shorthand: z.ZodOptional<z.ZodString>;
                             type: z.ZodString;
                             id: z.ZodString;
                             projectId: z.ZodOptional<z.ZodString>;
@@ -2550,6 +2565,7 @@ declare const workbenchExtensionMetadataSchema: z.ZodObject<{
                 id: z.ZodString;
             }, z.core.$strip>]>;
             resource: z.ZodOptional<z.ZodObject<{
+                shorthand: z.ZodOptional<z.ZodString>;
                 type: z.ZodString;
                 id: z.ZodString;
                 projectId: z.ZodOptional<z.ZodString>;
@@ -2593,6 +2609,7 @@ declare const workbenchExtensionMetadataSchema: z.ZodObject<{
                     id: z.ZodString;
                 }, z.core.$strip>]>;
                 resource: z.ZodOptional<z.ZodObject<{
+                    shorthand: z.ZodOptional<z.ZodString>;
                     type: z.ZodString;
                     id: z.ZodString;
                     projectId: z.ZodOptional<z.ZodString>;
@@ -2783,6 +2800,7 @@ declare const workbenchExtensionMetadataSchema: z.ZodObject<{
                 id: z.ZodString;
             }, z.core.$strip>]>;
             resource: z.ZodOptional<z.ZodObject<{
+                shorthand: z.ZodOptional<z.ZodString>;
                 type: z.ZodString;
                 id: z.ZodString;
                 projectId: z.ZodOptional<z.ZodString>;
@@ -2826,6 +2844,7 @@ declare const workbenchExtensionMetadataSchema: z.ZodObject<{
                     id: z.ZodString;
                 }, z.core.$strip>]>;
                 resource: z.ZodOptional<z.ZodObject<{
+                    shorthand: z.ZodOptional<z.ZodString>;
                     type: z.ZodString;
                     id: z.ZodString;
                     projectId: z.ZodOptional<z.ZodString>;

package/dist/client/index.js

@@ -499,21 +499,26 @@ var createSyncClient = (clientOptions) => ({
       if (event === "init")
         setConnected();
     };
+    const readConnection = async (signal) => {
+      const response = await resolveFetch(clientOptions)(resolveClientUrl(resolveBaseUrl(clientOptions), buildSyncStreamPath(lastSeq)), {
+        headers: Object.fromEntries(createRequestHeaders(clientOptions).entries()),
+        signal,
+        credentials: "same-origin"
+      });
+      if (!response.ok || !response.body)
+        throw new Error("SSE connection failed");
+      if (closed)
+        return;
+      if (lastSeq > 0)
+        setConnected();
+      await readSseStream(response.body, ({ event, data }) => handleEvent(event, data), { signal });
+    };
     const connect = async () => {
       if (closed)
         return;
       abortController = new AbortController;
       try {
-        const response = await resolveFetch(clientOptions)(resolveClientUrl(resolveBaseUrl(clientOptions), buildSyncStreamPath(lastSeq)), {
-          headers: Object.fromEntries(createRequestHeaders(clientOptions).entries()),
-          signal: abortController.signal,
-          credentials: "same-origin"
-        });
-        if (!response.ok || !response.body)
-          throw new Error("SSE connection failed");
-        await readSseStream(response.body, ({ event, data }) => handleEvent(event, data), {
-          signal: abortController.signal
-        });
+        await readConnection(abortController.signal);
       } catch (err) {
         if (closed || err.name === "AbortError")
           return;

package/dist/client.d.ts

@@ -157,6 +157,7 @@ declare const commandExecuteRequestSchema: z.ZodObject<{
     workspaceId: z.ZodOptional<z.ZodString>;
     params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     resource: z.ZodOptional<z.ZodObject<{
+        shorthand: z.ZodOptional<z.ZodString>;
         type: z.ZodString;
         id: z.ZodString;
         projectId: z.ZodOptional<z.ZodString>;
@@ -184,6 +185,7 @@ declare const commandExecuteRequestSchema: z.ZodObject<{
         mode: z.ZodOptional<z.ZodString>;
         projectId: z.ZodOptional<z.ZodString>;
         resource: z.ZodOptional<z.ZodObject<{
+            shorthand: z.ZodOptional<z.ZodString>;
             type: z.ZodString;
             id: z.ZodString;
             projectId: z.ZodOptional<z.ZodString>;
@@ -311,6 +313,7 @@ declare const createAutomationRunInputSchema: z.ZodObject<{
         workspaceId: z.ZodOptional<z.ZodString>;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         resource: z.ZodOptional<z.ZodObject<{
+            shorthand: z.ZodOptional<z.ZodString>;
             type: z.ZodString;
             id: z.ZodString;
             projectId: z.ZodOptional<z.ZodString>;
@@ -360,6 +363,7 @@ declare const createSessionInputSchema: z.ZodObject<{
     agent: z.ZodOptional<z.ZodString>;
     workspace_id: z.ZodOptional<z.ZodString>;
     anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        shorthand: z.ZodOptional<z.ZodString>;
         type: z.ZodString;
         id: z.ZodString;
         projectId: z.ZodOptional<z.ZodString>;
@@ -519,6 +523,7 @@ declare const followUpResponseSchema: z.ZodObject<{
     cwd: z.ZodNullable<z.ZodString>;
     params_json: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>>;
     anchors_json: z.ZodArray<z.ZodObject<{
+        shorthand: z.ZodOptional<z.ZodString>;
         type: z.ZodString;
         id: z.ZodString;
         projectId: z.ZodOptional<z.ZodString>;
@@ -1193,6 +1198,7 @@ declare const resolveSessionIdResponseSchema: z.ZodObject<{
 declare interface ResourceRef {
     type: string;
     id: string;
+    shorthand?: string;
     projectId?: string;
     label?: string;
     icon?: string;
@@ -1271,6 +1277,7 @@ declare const sessionConversationResponseSchema: z.ZodObject<{
         cwd: z.ZodNullable<z.ZodString>;
         params_json: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>>;
         anchors_json: z.ZodArray<z.ZodObject<{
+            shorthand: z.ZodOptional<z.ZodString>;
             type: z.ZodString;
             id: z.ZodString;
             projectId: z.ZodOptional<z.ZodString>;
@@ -1309,6 +1316,7 @@ declare const sessionSchema: z.ZodObject<{
     cwd: z.ZodNullable<z.ZodString>;
     params_json: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>>;
     anchors_json: z.ZodArray<z.ZodObject<{
+        shorthand: z.ZodOptional<z.ZodString>;
         type: z.ZodString;
         id: z.ZodString;
         projectId: z.ZodOptional<z.ZodString>;
@@ -1341,6 +1349,7 @@ export declare type SettingsClient = {
 };
 
 declare const settingsSchema: z.ZodObject<{
+    notifications_enabled: z.ZodBoolean;
     max_concurrent_sessions: z.ZodNullable<z.ZodNumber>;
 }, z.core.$strip>;
 
@@ -1432,6 +1441,7 @@ export declare type SseEvent = {
 };
 
 export declare type StartSyncInput = SyncWriterProvider & {
+    /** Called after the initial snapshot, or when a cursor-based connection resumes. */
     onConnected?: () => void;
     onDisconnected?: () => void;
     onConnectionLost?: () => void;
@@ -1475,6 +1485,7 @@ declare interface UpdateNotificationInput {
 declare type UpdateSettingsInput = z.infer<typeof updateSettingsInputSchema>;
 
 declare const updateSettingsInputSchema: z.ZodObject<{
+    notifications_enabled: z.ZodOptional<z.ZodBoolean>;
     max_concurrent_sessions: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strict>;
 
@@ -1640,6 +1651,7 @@ declare const workspaceListItemSchema: z.ZodObject<{
     workspace_shorthand: z.ZodString;
     startup_log_file_id: z.ZodNullable<z.ZodString>;
     anchors_json: z.ZodArray<z.ZodObject<{
+        shorthand: z.ZodOptional<z.ZodString>;
         type: z.ZodString;
         id: z.ZodString;
         projectId: z.ZodOptional<z.ZodString>;
@@ -1692,6 +1704,7 @@ declare const workspaceSchema: z.ZodObject<{
     workspace_shorthand: z.ZodString;
     startup_log_file_id: z.ZodNullable<z.ZodString>;
     anchors_json: z.ZodArray<z.ZodObject<{
+        shorthand: z.ZodOptional<z.ZodString>;
         type: z.ZodString;
         id: z.ZodString;
         projectId: z.ZodOptional<z.ZodString>;

package/dist/data/index.js

@@ -0,0 +1,115 @@
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/data/draft-layout.ts
+var assertSafePathSegment = (value) => {
+  if (!value || value === "." || value === ".." || /[/\\\0]/.test(value))
+    throw new Error(`Unsafe path segment: ${value}`);
+};
+var requireRepoFiles = (repoFiles) => {
+  if (!repoFiles)
+    throw new Error("This command must be run inside a project repository.");
+  return repoFiles;
+};
+var createDraftLayout = (root, document) => {
+  const directory = (name) => {
+    assertSafePathSegment(name);
+    return `${root}/${name}`;
+  };
+  return {
+    directory,
+    markdown: (name, suffix = "") => `${directory(name)}/${document}${suffix}.md`,
+    files: (name, suffix = "") => `${directory(name)}/files${suffix}`
+  };
+};
+// src/data/frontmatter.ts
+var escapeYamlScalar = (value) => value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n");
+var quoteYamlScalar = (value) => `"${escapeYamlScalar(value)}"`;
+var findClosingFrontmatterDelimiter = (content) => {
+  const match = /\n---[ \t]*(?:\r?\n|$)/.exec(content.slice(3));
+  if (!match)
+    return null;
+  const start = 3 + match.index + 1;
+  const end = 3 + match.index + match[0].length;
+  return { end, start };
+};
+var stripFrontmatter = (content) => {
+  if (!content.startsWith("---"))
+    return content;
+  const delimiter = findClosingFrontmatterDelimiter(content);
+  if (!delimiter)
+    return content;
+  return content.slice(delimiter.end);
+};
+var applyFrontmatter = (frontmatter, content) => {
+  const body = stripFrontmatter(content).replace(/^\n+/, "");
+  if (!body)
+    return frontmatter;
+  return `${frontmatter}
+
+${body}`;
+};
+var unescapeYamlScalar = (value) => {
+  let result = "";
+  for (let index = 0;index < value.length; index++) {
+    const current = value[index];
+    const next = value[index + 1];
+    if (current !== "\\" || next === undefined) {
+      result += current;
+      continue;
+    }
+    if (next === "n")
+      result += `
+`;
+    else if (next === '"')
+      result += '"';
+    else if (next === "\\")
+      result += "\\";
+    else
+      result += `${current}${next}`;
+    index++;
+  }
+  return result;
+};
+var unquoteYamlScalar = (value) => {
+  const quoted = value.match(/^(["'])(.*)\1$/);
+  return quoted ? unescapeYamlScalar(quoted[2] ?? "") : value;
+};
+// src/data/resolve.ts
+var sameName = (a, b) => a.trim().toLowerCase() === b.trim().toLowerCase();
+var resolveByIdOrName = (items, value, nameOf, label) => {
+  const byId = items.find((item) => item.id === value);
+  if (byId)
+    return byId.id;
+  const byName = items.filter((item) => sameName(nameOf(item), value));
+  if (byName.length > 1)
+    throw new Error(`Ambiguous ${label} "${value}"`);
+  const [match] = byName;
+  if (match)
+    return match.id;
+  throw new Error(`Unknown ${label} "${value}"`);
+};
+export {
+  unquoteYamlScalar,
+  stripFrontmatter,
+  sameName,
+  resolveByIdOrName,
+  requireRepoFiles,
+  quoteYamlScalar,
+  findClosingFrontmatterDelimiter,
+  createDraftLayout,
+  assertSafePathSegment,
+  applyFrontmatter
+};

package/dist/data.d.ts

@@ -0,0 +1,47 @@
+export declare const applyFrontmatter: (frontmatter: string, content: string) => string;
+
+declare interface ArtifactFile {
+    path: string;
+    size?: number;
+    updatedAt?: string;
+}
+
+declare interface ArtifactMount {
+    exists(path: string): Promise<boolean>;
+    readText(path: string): Promise<string>;
+    writeText(path: string, value: string): Promise<void>;
+    readBytes(path: string): Promise<Uint8Array>;
+    writeBytes(path: string, value: Uint8Array): Promise<void>;
+    list(pattern?: string): Promise<ArtifactFile[]>;
+    listDirs(path?: string): Promise<string[]>;
+    delete(path: string): Promise<void>;
+}
+
+export declare const assertSafePathSegment: (value: string) => void;
+
+export declare const createDraftLayout: (root: string, document: string) => {
+    directory: (name: string) => string;
+    markdown: (name: string, suffix?: string) => string;
+    files: (name: string, suffix?: string) => string;
+};
+
+export declare const findClosingFrontmatterDelimiter: (content: string) => {
+    end: number;
+    start: number;
+} | null;
+
+export declare const quoteYamlScalar: (value: string) => string;
+
+export declare const requireRepoFiles: (repoFiles: ArtifactMount | undefined) => ArtifactMount;
+
+export declare const resolveByIdOrName: <TItem extends {
+    id: string;
+}>(items: TItem[], value: string, nameOf: (item: TItem) => string, label: string) => string;
+
+export declare const sameName: (a: string, b: string) => boolean;
+
+export declare const stripFrontmatter: (content: string) => string;
+
+export declare const unquoteYamlScalar: (value: string) => string;
+
+export { }