synomem 0.4.0 → 0.5.0

package/src/cli.ts

@@ -21,6 +21,7 @@ import {
   type ConfigPlan,
   type CredentialStoreChoice,
 } from './configure.js';
+import { discoverBoundWorkspace, discoverOrganizations, workspaceChoices } from './discover.js';
 import { defaultPromptIo, type PromptIo } from './prompt.js';
 import { credentialReference, OsCredentialStore, type CredentialStore } from './credentials.js';
 import { asSynomemError, SynomemError, type SynomemErrorCode } from './errors.js';
@@ -45,6 +46,7 @@ import {
 } from './skill-install.js';
 import type {
   ActorIdentity,
+  AgentRuntimeBinding,
   EvidenceReference,
   KudosListInput,
   KudosRecord,
@@ -74,6 +76,14 @@ export interface CliDependencies {
     reference: string;
     credentialStore: CredentialStore;
   }) => Promise<void>;
+  /*
+   * Injected so setup can be tested without a network. The default asks the
+   * service which workspace an access key is bound to.
+   */
+  discoverBoundWorkspace?: (options: {
+    baseUrl: string;
+    accessToken: string;
+  }) => Promise<{ workspaceId: string }>;
   createImportBundle?: (home: string) => Promise<ImportBundle>;
   remoteImport?: (options: {
     baseUrl: string;
@@ -300,6 +310,7 @@ export function createCli(
   const env = dependencies.env ?? process.env;
   const credentialStore = dependencies.credentialStore ?? new OsCredentialStore();
   const oauthLogin = dependencies.oauthLogin ?? loginWithOAuth;
+  const discoverWorkspace = dependencies.discoverBoundWorkspace ?? discoverBoundWorkspace;
   const promptIo = dependencies.promptIo ?? defaultPromptIo();
   const verifyRemoteCredential =
     dependencies.verifyRemoteCredential ??
@@ -340,6 +351,51 @@ export function createCli(
     .configureOutput({ writeOut: io.stdout, writeErr: io.stderr });
 
   const remoteCommand = program.command('remote').description('Administer a remote workspace');
+
+  /*
+   * The browser counterpart to an access key naming its own workspace.
+   *
+   * A signed-in account may reach several organizations, each with several
+   * workspaces, so there is a genuine choice to make -- and no way to make it
+   * without seeing the list. Printing the IDs alongside the names is the point:
+   * the ID is what `backend use remote --workspace` takes.
+   */
+  remoteCommand
+    .command('workspaces')
+    .description('List the organizations and workspaces this credential can reach')
+    .option('--url <url>', 'internal: alternate HTTPS origin')
+    .action(async (options: { url?: string }, command: Command) => {
+      const global = globals(command);
+      const config = readSynomemConfig(global.home, env);
+      const baseUrl =
+        options.url ??
+        (config?.backend.kind === 'remote' ? config.backend.baseUrl : cloudApiUrl(env));
+      const accessToken = env.SYNOMEM_ACCESS_TOKEN;
+      if (!accessToken) {
+        throw new SynomemError(
+          'AUTH_REQUIRED',
+          'Set SYNOMEM_ACCESS_TOKEN, or run `synomem auth login` first.',
+        );
+      }
+      const organizations = await discoverOrganizations({ baseUrl, accessToken });
+      const choices = workspaceChoices(organizations);
+      const human = organizations.length
+        ? organizations
+            .map((organization) =>
+              [
+                `${organization.displayName} (${organization.slug}) — ${organization.role}`,
+                ...(organization.workspaces.length
+                  ? organization.workspaces.map(
+                      (workspace) => `  ${workspace.id}  ${workspace.displayName}`,
+                    )
+                  : ['  (no workspaces yet)']),
+              ].join('\n'),
+            )
+            .join('\n')
+        : 'This account belongs to no organizations yet.';
+      output(io, global.json, { organizations, choices }, human);
+    });
+
   remoteCommand
     .command('import')
     .description('Preview or confirm a one-way import from a local Synomem home')
@@ -452,14 +508,53 @@ export function createCli(
     global: { home?: string; json: boolean },
   ): Promise<void> => {
     const home = plan.home;
+    const serviceUrl = plan.serviceUrl ?? cloudApiUrl(env);
+
+    /*
+     * The workspace is discovered, not typed.
+     *
+     * An installation access key is bound to exactly one workspace, so the
+     * service can be asked which one rather than the person. An explicit
+     * --workspace still wins, because automation should not depend on a
+     * network round trip to configure a machine.
+     */
+    let workspaceId = plan.workspaceId;
+    if (plan.backend === 'remote' && !workspaceId && token) {
+      const bound = await discoverWorkspace({ baseUrl: serviceUrl, accessToken: token });
+      workspaceId = bound.workspaceId;
+      io.stdout(`Access key is bound to workspace ${workspaceId}.\n`);
+    }
+    if (plan.backend === 'remote' && !workspaceId) {
+      /*
+       * Signing in through a browser needs an actor identity and a client ID,
+       * which is `synomem auth login`'s job. Rather than write a remote
+       * backend with no workspace -- a configuration that fails on its first
+       * real use -- say exactly what remains.
+       */
+      output(
+        io,
+        global.json,
+        { applied: false, pending: 'sign-in', home, serviceUrl },
+        [
+          '',
+          'Nothing was configured yet: signing in through a browser is a separate step.',
+          '',
+          'Run, with the actor this machine acts as:',
+          '',
+          '  synomem auth login --actor-id <agent> --client-id <client>',
+          '',
+          'Then select the workspace it reports:',
+          '',
+          '  synomem backend use remote --workspace <workspace-id>',
+        ].join('\n'),
+      );
+      return;
+    }
+
     const config = writeSynomemBackend(
       plan.backend === 'local'
         ? { kind: 'local' }
-        : {
-            kind: 'remote',
-            baseUrl: plan.serviceUrl ?? cloudApiUrl(env),
-            workspaceId: plan.workspaceId!,
-          },
+        : { kind: 'remote', baseUrl: serviceUrl, workspaceId: workspaceId! },
       home,
     );
 
@@ -474,7 +569,7 @@ export function createCli(
         // The platform store is the default, and a failure falls back to the
         // restricted file rather than leaving the credential nowhere.
         try {
-          await credentialStore.set(`synomem:${plan.workspaceId}`, {
+          await credentialStore.set(`synomem:${workspaceId}`, {
             kind: 'installation-key',
             accessToken: token,
           });
@@ -559,8 +654,13 @@ export function createCli(
           throw new SynomemError('INVALID_INPUT', 'Pass --backend local or --backend remote.');
         }
         const backend: BackendChoice = options.backend;
-        if (backend === 'remote' && !options.workspace) {
-          throw new SynomemError('INVALID_INPUT', 'Remote setup requires --workspace.');
+        // An access key names its own workspace, so --workspace is only
+        // required when there is no key to ask.
+        if (backend === 'remote' && !options.workspace && !options.accessTokenStdin) {
+          throw new SynomemError(
+            'INVALID_INPUT',
+            'Remote setup requires --workspace, or --access-token-stdin so the key can name its own.',
+          );
         }
         const token = options.accessTokenStdin ? await readAccessToken(promptIo) : undefined;
         if (backend === 'remote' && options.auth === 'access-key' && !token) {
@@ -745,6 +845,92 @@ export function createCli(
       );
     });
 
+  /*
+   * `show` reads the config file; `status` proves the selection actually works.
+   *
+   * The two are deliberately separate. A person debugging a broken setup needs
+   * to know what is configured even when nothing can be reached, and a person
+   * checking that a setup is live needs a connection to have been made. One
+   * command doing both would make a printed workspace ID look like a reachable
+   * workspace.
+   */
+  backendCommand
+    .command('status')
+    .description('Connect to the selected backend and report what answered')
+    .action(async (_options, command: Command) => {
+      const global = globals(command);
+      const config = readSynomemConfig(global.home);
+      if (!config) {
+        throw new SynomemError(
+          'CONFIG_INVALID',
+          'No Synomem home here yet. Run `synomem config init` first.',
+        );
+      }
+      const result = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli'),
+        async (client) => ({
+          info: await client.info(),
+          capabilities: await client.capabilities(),
+          diagnostics: (await client.doctor()).diagnostics.filter(
+            (item) => item.level === 'error' || item.level === 'warning',
+          ),
+        }),
+      );
+      const { info, capabilities, diagnostics } = result;
+      const where =
+        info.backend === 'local'
+          ? `Home: ${info.home}\nDatabase: ${info.databasePath}`
+          : `URL: ${info.baseUrl}`;
+      const problems = diagnostics.length
+        ? diagnostics
+            .map((item) => `${item.level.toUpperCase()} ${item.code}: ${item.message}`)
+            .join('\n')
+        : 'No warnings or errors.';
+      const human = [
+        `Backend: ${info.backend} (reachable)`,
+        where,
+        `Workspace: ${capabilities.binding.workspaceId}`,
+        `Acting as: ${capabilities.binding.actor.kind} ${capabilities.binding.actor.id}`,
+        problems,
+      ].join('\n');
+      output(io, global.json, { reachable: true, info, capabilities, diagnostics }, human);
+      if (diagnostics.some((item) => item.level === 'error')) cliExitCodes.set(program, 5);
+    });
+
+  const projectionCommand = program
+    .command('projection')
+    .description('Inspect the generated files Synomem derives from events');
+  projectionCommand
+    .command('status')
+    .description('Report whether the generated files match the canonical events')
+    .action(async (_options, command: Command) => {
+      const global = globals(command);
+      const status = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) => {
+        if (!client.projectionStatus) {
+          throw new SynomemError(
+            'INVALID_INPUT',
+            'The remote backend keeps no filesystem projections, so there is nothing to report.',
+          );
+        }
+        return client.projectionStatus();
+      });
+      const enabled = Object.entries(status.settings)
+        .filter(([, on]) => on)
+        .map(([name]) => name);
+      const lines = [
+        `Directory: ${status.directory ?? '(none)'}`,
+        `Enabled: ${enabled.length ? enabled.join(', ') : 'none'}`,
+        `Last rebuilt: ${status.lastRebuiltAt ?? 'never'}`,
+        status.current
+          ? `Current: ${status.counts.manifest} generated file(s) match the events.`
+          : `Stale: ${status.counts.missing} missing, ${status.counts.unexpected} no longer expected. Run \`synomem rebuild\`.`,
+      ];
+      for (const path of status.missing) lines.push(`  missing     ${path}`);
+      for (const path of status.unexpected) lines.push(`  unexpected  ${path}`);
+      output(io, global.json, status, lines.join('\n'));
+    });
+
   const authCommand = program.command('auth').description('Inspect remote authentication');
   authCommand
     .command('status')
@@ -1245,23 +1431,45 @@ export function createCli(
       },
     );
 
+  /*
+   * With no agent named this answers the question people actually arrive with:
+   * "where is any of my stuff running?". Naming an agent narrows it. Requiring
+   * the agent, as this once did, means you must already know the answer to the
+   * question you came to ask.
+   */
   runtimeCommand
-    .command('list <agent>')
-    .description('List an agent runtime bindings')
-    .action(async (agent: string, _options, command: Command) => {
+    .command('list [agent]')
+    .description('List runtime bindings for one agent, or for every agent')
+    .action(async (agent: string | undefined, _options, command: Command) => {
       const global = globals(command);
-      const bindings = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) =>
-        client.agents.bindings(agent),
+      const result = await withClient(
+        global.home,
+        defaultActor(env, 'system', 'cli'),
+        async (client) => {
+          if (agent) {
+            const profile = await client.agents.get(agent);
+            return [{ profile, runtimeBindings: await client.agents.bindings(agent) }];
+          }
+          return (await client.agents.directory()).filter(
+            (entry) => entry.runtimeBindings.length > 0,
+          );
+        },
       );
-      const human = bindings.length
-        ? bindings
-            .map(
-              (binding) =>
-                `${binding.id}  ${binding.runtime}${binding.profile ? `/${binding.profile}` : ''}  bound ${binding.boundAt}`,
+      const describe = (binding: AgentRuntimeBinding) =>
+        `  ${binding.id}  ${binding.runtime}${binding.profile ? `/${binding.profile}` : ''}  bound ${binding.boundAt}`;
+      const human = result.length
+        ? result
+            .map((entry) =>
+              [
+                `${entry.profile.handle} (${entry.profile.id})`,
+                ...entry.runtimeBindings.map(describe),
+              ].join('\n'),
             )
             .join('\n')
-        : 'No runtime bindings.';
-      output(io, global.json, { bindings }, human);
+        : agent
+          ? 'No runtime bindings.'
+          : 'No agent in this workspace has a runtime binding.';
+      output(io, global.json, { agents: result }, human);
     });
 
   runtimeCommand

package/src/client.ts

@@ -58,6 +58,7 @@ import type {
   UpdatePostInput,
   Diagnostic,
   DoctorResult,
+  ProjectionStatus,
   GiveKudosInput,
   GiveKudosResult,
   SendMemoInput,
@@ -1692,6 +1693,41 @@ export class SynomemClient extends SynomemCore implements SynomemService {
     this.projections = projections;
   }
 
+  /*
+   * Answers "would a rebuild change anything, and when did one last run?"
+   *
+   * The comparison is against the manifest rather than a directory walk, so a
+   * file a person dropped into the projection tree by hand is not reported as
+   * drift -- Synomem only claims authority over what it wrote.
+   */
+  async projectionStatus(): Promise<ProjectionStatus> {
+    this.checkAbort();
+    const expected = this.projections.expectedPaths();
+    const entries = this.storage.projectionManifestEntries();
+    const manifest = entries.map((entry) => entry.path);
+    const inManifest = new Set(manifest);
+    const inExpected = new Set(expected);
+    const missing = expected.filter(
+      (path) => !inManifest.has(path) || !existsSync(join(this.home, path)),
+    );
+    const unexpected = manifest.filter((path) => !inExpected.has(path));
+    const limit = 20;
+    return {
+      directory: this.home,
+      settings: { ...this.storage.config.projection },
+      current: missing.length === 0 && unexpected.length === 0,
+      ...(entries[0] ? { lastRebuiltAt: entries[0].generatedAt } : {}),
+      counts: {
+        expected: expected.length,
+        manifest: manifest.length,
+        missing: missing.length,
+        unexpected: unexpected.length,
+      },
+      missing: missing.slice(0, limit),
+      unexpected: unexpected.slice(0, limit),
+    };
+  }
+
   async doctor(): Promise<DoctorResult> {
     this.checkAbort();
     const diagnostics: Diagnostic[] = [];
@@ -1791,7 +1827,11 @@ export class SynomemClient extends SynomemCore implements SynomemService {
           : 'Projection manifest is current.',
       });
       for (const profile of this.storage.listAgents()) {
-        const directory = join(this.home, profile.id);
+        // Named by handle, which is what the projection writers create. Using
+        // the canonical ID here checks a directory that does not exist, which
+        // makes the check pass on a workspace whose agent directory really has
+        // been replaced with a symbolic link.
+        const directory = join(this.home, profile.handle);
         try {
           assertNoSymlinkEscape(this.home, directory);
           if (existsSync(directory) && lstatSync(directory).isSymbolicLink()) {

package/src/configure.ts

@@ -51,10 +51,17 @@ export function credentialStoreChoices(
     platform === 'darwin'
       ? { value: 'keychain' as const, label: 'macOS Keychain', detail: 'Recommended.' }
       : platform === 'win32'
-        ? {
-            value: 'keychain' as const,
-            label: 'Windows Credential Manager',
-            detail: 'Recommended.',
+        ? /*
+           * Windows has no native option here yet, so the restricted file is
+           * the recommendation rather than Credential Manager. Offering a
+           * store the credential layer cannot actually read back would fail
+           * at the first use, after the wizard had already told the person
+           * their credential was safely stored.
+           */
+          {
+            value: 'file' as const,
+            label: 'A restricted file in the Synomem home',
+            detail: 'Recommended on Windows until Credential Manager support lands.',
           }
         : {
             value: 'keychain' as const,
@@ -63,11 +70,15 @@ export function credentialStoreChoices(
           };
   return [
     native,
-    {
-      value: 'file',
-      label: 'A restricted file in the Synomem home',
-      detail: 'Mode 0600. Use on headless machines with no keyring.',
-    },
+    ...(native.value === 'file'
+      ? []
+      : [
+          {
+            value: 'file' as const,
+            label: 'A restricted file in the Synomem home',
+            detail: 'Mode 0600. Use on headless machines with no keyring.',
+          },
+        ]),
     {
       value: 'environment',
       label: 'Print environment-variable instructions',
@@ -185,10 +196,15 @@ export async function runConfigWizard(
     },
   ]);
 
-  const workspaceId = await ask(io, 'Workspace ID');
-  if (!workspaceId) {
-    throw new SynomemError('INVALID_INPUT', 'A workspace ID is required for the hosted backend.');
-  }
+  /*
+   * Deliberately no workspace prompt here.
+   *
+   * A hosted workspace ID looks like `ws-04psqx2rkt8ttft7a1t2z69r97`, and the
+   * credential authorized in the next step already knows which workspace it
+   * reaches -- an installation key is bound to exactly one, and a browser
+   * sign-in can list the ones the account belongs to. Asking first means
+   * asking a person to go and look something up that we are about to be told.
+   */
 
   const credentialStore =
     auth === 'access-key'
@@ -199,7 +215,7 @@ export async function runConfigWizard(
         )
       : 'auto';
 
-  return { backend, home, serviceUrl, auth, workspaceId, credentialStore };
+  return { backend, home, serviceUrl, auth, credentialStore };
 }
 
 /** Reads an access key without ever accepting it as an argument. */

package/src/credentials.ts

@@ -200,10 +200,18 @@ export class OsCredentialStore implements CredentialStore {
     return result.code === 0;
   }
 
+  /*
+   * Windows Credential Manager is not implemented yet. `cmdkey` can write a
+   * generic credential but deliberately will not read the secret back, so a
+   * store built on it would accept a credential and then never return it --
+   * worse than saying so plainly.
+   */
   private unsupported(): never {
     throw new SynomemError(
       'CONFIG_INVALID',
-      'Interactive credential storage is currently supported on macOS and Linux with secret-tool.',
+      this.platform === 'win32'
+        ? 'Windows Credential Manager storage is not supported yet. Run `synomem config init` and choose the restricted-file store, or set SYNOMEM_ACCESS_TOKEN.'
+        : 'Operating-system credential storage needs the macOS Keychain, or secret-tool on Linux. Run `synomem config init` and choose the restricted-file store, or set SYNOMEM_ACCESS_TOKEN.',
     );
   }
 }

package/src/discover.ts

@@ -0,0 +1,155 @@
+/*
+ * Finding out which workspace a credential belongs to, so nobody has to type
+ * one from memory.
+ *
+ * A hosted workspace ID looks like `ws-04psqx2rkt8ttft7a1t2z69r97`. Asking a
+ * person to enter that during setup is asking them to leave and go find it, and
+ * the credential they just authorized already knows the answer -- or knows
+ * enough to offer a short list.
+ *
+ * Two credentials, two routes, because they carry different authority:
+ *
+ *   An installation access key is bound to exactly one workspace. There is
+ *   nothing to choose, so `discoverBoundWorkspace` reads it off the data plane
+ *   and setup asks nothing at all.
+ *
+ *   A browser sign-in authorizes an ACCOUNT, which may reach several
+ *   organizations, each with several workspaces. `discoverOrganizations` lists
+ *   them for selection.
+ */
+import { SynomemError } from './errors.js';
+
+export interface DiscoveredWorkspace {
+  id: string;
+  displayName: string;
+}
+
+export interface DiscoveredOrganization {
+  id: string;
+  slug: string;
+  displayName: string;
+  role: string;
+  workspaces: DiscoveredWorkspace[];
+}
+
+export interface DiscoveryOptions {
+  baseUrl: string;
+  accessToken: string;
+  /** Injected by tests. Defaults to the global fetch. */
+  fetch?: typeof globalThis.fetch;
+  signal?: AbortSignal;
+}
+
+interface Envelope<T> {
+  ok?: boolean;
+  data?: T;
+  error?: { code?: string; message?: string };
+}
+
+async function readJson<T>(options: DiscoveryOptions, path: string): Promise<T> {
+  const request = options.fetch ?? globalThis.fetch;
+  const url = new URL(
+    path,
+    options.baseUrl.endsWith('/') ? options.baseUrl : `${options.baseUrl}/`,
+  );
+  let response: Response;
+  try {
+    response = await request(url, {
+      headers: { authorization: `Bearer ${options.accessToken}`, accept: 'application/json' },
+      ...(options.signal ? { signal: options.signal } : {}),
+    });
+  } catch (error) {
+    throw new SynomemError(
+      'REMOTE_UNAVAILABLE',
+      `Could not reach ${url.origin}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  let body: Envelope<T>;
+  try {
+    body = (await response.json()) as Envelope<T>;
+  } catch {
+    throw new SynomemError('REMOTE_PROTOCOL', `${url.pathname} did not return JSON.`);
+  }
+  if (!response.ok || body.ok !== true || body.data === undefined) {
+    // 401 and 403 are the ones a person can act on, so they keep their own
+    // codes rather than being flattened into a generic protocol error.
+    const code =
+      response.status === 401 ? 'AUTH_REQUIRED' : response.status === 403 ? 'AUTH_FORBIDDEN' : null;
+    const message = body.error?.message ?? `${url.pathname} returned ${response.status}.`;
+    throw new SynomemError(code ?? 'REMOTE_PROTOCOL', message);
+  }
+  return body.data;
+}
+
+/**
+ * The single workspace an installation access key can address.
+ *
+ * Answered by the data plane rather than the control plane: an installation key
+ * is not an account principal, so it cannot list organizations, but it can
+ * always say where it is bound.
+ */
+export async function discoverBoundWorkspace(
+  options: DiscoveryOptions,
+): Promise<{ workspaceId: string; actor: { kind: string; id: string; displayName?: string } }> {
+  const identity = await readJson<{
+    workspaceId: string;
+    actor: { kind: string; id: string; displayName?: string };
+  }>(options, 'v1/identity');
+  if (!identity.workspaceId) {
+    throw new SynomemError('REMOTE_PROTOCOL', 'The service did not report a bound workspace.');
+  }
+  return { workspaceId: identity.workspaceId, actor: identity.actor };
+}
+
+/**
+ * Every organization this account belongs to, each with its workspaces.
+ *
+ * Organizations are listed even when they hold no workspaces yet, because
+ * "you belong to this organization and it is empty" is a different and more
+ * useful answer than omitting it and appearing to have found nothing.
+ */
+export async function discoverOrganizations(
+  options: DiscoveryOptions,
+): Promise<DiscoveredOrganization[]> {
+  const me = await readJson<{
+    organizations: { id: string; slug: string; displayName: string; role: string }[];
+  }>(options, 'v1/me');
+  const organizations: DiscoveredOrganization[] = [];
+  for (const organization of me.organizations ?? []) {
+    const workspaces = await readJson<{ id: string; displayName: string }[]>(
+      options,
+      `v1/organizations/${encodeURIComponent(organization.id)}/workspaces`,
+    );
+    organizations.push({
+      id: organization.id,
+      slug: organization.slug,
+      displayName: organization.displayName,
+      role: organization.role,
+      workspaces: (workspaces ?? []).map((workspace) => ({
+        id: workspace.id,
+        displayName: workspace.displayName,
+      })),
+    });
+  }
+  return organizations;
+}
+
+/** Flattens discovery into the choices a person picks from. */
+export function workspaceChoices(
+  organizations: DiscoveredOrganization[],
+): Array<{ value: string; label: string; detail?: string }> {
+  const choices: Array<{ value: string; label: string; detail?: string }> = [];
+  for (const organization of organizations) {
+    for (const workspace of organization.workspaces) {
+      choices.push({
+        value: workspace.id,
+        // The organization is part of the label, not the detail: two
+        // organizations may both have a workspace called "Production", and the
+        // label is the only part a person is guaranteed to read.
+        label: `${organization.displayName} / ${workspace.displayName}`,
+        detail: workspace.id,
+      });
+    }
+  }
+  return choices;
+}

package/src/index.ts

@@ -41,6 +41,8 @@ export type {
 } from './service.js';
 export { defaultConfig, resolveHome } from './config.js';
 export { cloudApiUrl, SYNOMEM_CLOUD_API_URL } from './cloud.js';
+export { discoverBoundWorkspace, discoverOrganizations, workspaceChoices } from './discover.js';
+export type { DiscoveredOrganization, DiscoveredWorkspace, DiscoveryOptions } from './discover.js';
 export { asSynomemError, errorCodes, SynomemError } from './errors.js';
 export {
   dueInstant,