@lanes-sh/link 0.6.11 → 0.7.0

package/src/cli/commands/connect/setup.ts

@@ -115,7 +115,7 @@ export function reuseStoredCredential(input: {
 /**
  * Ask for a static credential — an API key, or an app-specific password.
  *
- * This did not exist, which meant the custom-provider path `docs/detailed/creating-a-provider.md`
+ * This did not exist, which meant the custom-provider path `https://lanes.sh/docs/link/creating-a-provider`
  * documents did not work: a manifest declaring `auth: {kind: header}` connected
  * with no complaint, never asked for the key, and then reported itself
  * unauthorized forever — with `doctor` advising the very command that had just

package/src/cli/commands/connect/variables.ts

@@ -0,0 +1,220 @@
+import type { AnyConnector, ProviderManifest } from '#connectivity';
+import { connectorFactory, type ConnectorFactory } from '#connectivity/transports';
+import type { ProviderRegistry } from '#registry';
+
+/** Only the fields this reads; the real row carries more. */
+interface ConnectionRow {
+  readonly provider: string;
+  readonly id: string;
+  readonly config?: Readonly<Record<string, unknown>> | undefined;
+}
+import type { SecretStore } from '#secrets';
+import type { Prompter } from '../../prompt.ts';
+
+/**
+ * Asking a connection where its service is.
+ *
+ * Only a provider that declares `variables` reaches this — a Zendesk-shaped host
+ * that carries the tenant, or anything self-hosted. Everything else has one
+ * address for everybody and is never asked anything here.
+ *
+ * Asked *before* the account is settled, and that ordering is forced rather than
+ * chosen: settling the identity means calling the service, and there is nothing
+ * to call until the address is known. It is also why the values cannot simply be
+ * written to the connection row first — the row's id is not decided until the
+ * identity comes back.
+ */
+export interface VariableValues {
+  readonly [key: string]: string;
+}
+
+export async function askForVariables(input: {
+  readonly manifest: ProviderManifest;
+  readonly prompter: Prompter;
+  /** Values already on the row, when reconnecting. Offered as the default. */
+  readonly existing?: Readonly<Record<string, unknown>> | undefined;
+  /** With nobody to ask, an absent value is a refusal rather than a prompt. */
+  readonly interactive: boolean;
+  /** From `--set key=value`, which is how a non-interactive run supplies one. */
+  readonly supplied?: Readonly<Record<string, string>> | undefined;
+}): Promise<VariableValues> {
+  const { manifest, prompter, existing, interactive } = input;
+  const supplied = input.supplied ?? {};
+  if (manifest.variables.length === 0) return {};
+
+  const values: Record<string, string> = {};
+
+  for (const variable of manifest.variables) {
+    // `--set` outranks what the row already carries: naming a value is how
+    // somebody says the server moved.
+    const previous = supplied[variable.key] ?? existing?.[variable.key];
+    const known = typeof previous === 'string' && previous !== '' ? previous : undefined;
+
+    if (!interactive) {
+      if (!known) {
+        throw new Error(
+          `${manifest.name} needs to be told its ${variable.label} and there is nobody to ask. ` +
+            `Give it on the command line: --set ${variable.key}=${variable.example}`,
+        );
+      }
+      if (!new RegExp(variable.pattern).test(known)) {
+        throw new Error(
+          `"${known}" is not a usable ${variable.label} — it must look like ${variable.example}.`,
+        );
+      }
+      values[variable.key] = known;
+      continue;
+    }
+
+    // The description goes in the question rather than beside it: `Prompter.ask`
+    // takes one string, and a hostname nobody can guess needs the sentence that
+    // says where to find it.
+    const answer = (
+      await prompter.ask(
+        `${variable.description}\n${variable.label}${known ? ` [${known}]` : ` (e.g. ${variable.example})`}`,
+      )
+    ).trim();
+
+    const chosen = answer === '' ? known : answer;
+    if (!chosen) {
+      throw new Error(`${manifest.name} cannot be reached without its ${variable.label}.`);
+    }
+
+    // Checked here as well as at substitution, so a mistyped subdomain is a
+    // question asked again rather than a connection that is written and then
+    // fails on its first call. `applyVariables` is still the one that matters —
+    // it guards the value a *file* supplies, which never passes through here.
+    if (!new RegExp(variable.pattern).test(chosen)) {
+      throw new Error(
+        `"${chosen}" is not a usable ${variable.label} — it must look like ${variable.example}. ` +
+          `The value goes into the address this connection calls, so anything that could change ` +
+          `the host is refused.`,
+      );
+    }
+
+    values[variable.key] = chosen;
+  }
+
+  return values;
+}
+
+/**
+ * The address a provider was last given, from whichever of its connections has one.
+ *
+ * Also reached across a family: `nextcloud_calendar` and `nextcloud_contacts`
+ * are two providers on one server, and the setup steps tell people to connect
+ * them together — so being asked the same hostname twice is the thing to avoid.
+ * They are matched on sharing a credential app, which is already how "one
+ * account, several providers" is expressed.
+ */
+function previousAddress(
+  connections: readonly ConnectionRow[],
+  providerId: string,
+  manifest: ProviderManifest,
+): Readonly<Record<string, unknown>> | undefined {
+  const family = manifest.auth.kind === 'basic' ? manifest.auth.app : undefined;
+
+  const mine = connections.find(
+    (connection) => connection.provider === providerId && connection.config,
+  );
+  if (mine) return mine.config;
+
+  if (!family) return undefined;
+
+  return connections.find(
+    (connection) => connection.provider.startsWith(`${family}_`) && connection.config,
+  )?.config;
+}
+
+export interface ResolvedAddress {
+  /** What the connection will store under `config`. Empty for a fixed-address provider. */
+  readonly values: VariableValues;
+  /** The factory the identity probe and discovery should use. */
+  readonly connectorFor: (providerId: string, connectionId: string) => AnyConnector | undefined;
+  /** Only ever a scoped factory; the runtime's own is never closed by this. */
+  close(): Promise<void>;
+}
+
+/**
+ * Everything a connect run needs in order to reach a service whose address it
+ * has just been told.
+ *
+ * The scoped factory is the part worth explaining. The values belong to a
+ * connection row that does not exist yet — the row is written at step 4, and
+ * the id it will carry is not settled until step 2 — so there is nowhere for
+ * the runtime's own lookup to read them from. Rather than write a provisional
+ * row and rename it, this run gets a factory of its own holding the values
+ * directly. The runtime's factory is untouched, which matters because its cache
+ * is what keeps a stateful connector a single instance.
+ *
+ * A provider with no variables gets the runtime's factory back and no second
+ * cache, so the ordinary path is exactly as it was.
+ */
+export async function resolveConnectionAddress(input: {
+  readonly manifest: ProviderManifest;
+  readonly prompter: Prompter;
+  readonly providerId: string;
+  readonly provisionalId: string;
+  readonly interactive: boolean;
+  /** `--set key=value`, as the parser hands it over: absent, one, or many. */
+  readonly set?: readonly string[] | string | undefined;
+  readonly runtime: {
+    readonly registry: ProviderRegistry;
+    readonly credentials: SecretStore;
+    readonly config: { readonly connections: readonly ConnectionRow[] };
+    connectorFor(providerId: string, connectionId: string): AnyConnector | undefined;
+  };
+}): Promise<ResolvedAddress> {
+  const { manifest, runtime } = input;
+
+  const values = await askForVariables({
+    manifest,
+    prompter: input.prompter,
+    // What was said last time, offered as the default.
+    //
+    // Not keyed on the provisional id, which is `pending` unless `--id` was
+    // given — so the lookup almost never hit and every reconnect asked for the
+    // server address again. Any declared connection of this provider will do:
+    // the id is not settled yet, and a second Nextcloud on a *different* host is
+    // rarer than reconnecting the one there is. It is offered, not imposed —
+    // pressing Enter accepts it and typing replaces it.
+    existing: previousAddress(runtime.config.connections, input.providerId, manifest),
+    interactive: input.interactive,
+    supplied: parseSet(input.set),
+  });
+
+  if (manifest.variables.length === 0) {
+    return {
+      values,
+      connectorFor: runtime.connectorFor.bind(runtime),
+      close: async () => {},
+    };
+  }
+
+  const scoped: ConnectorFactory = connectorFactory({
+    registry: runtime.registry,
+    credentials: runtime.credentials,
+    connectionConfig: () => values,
+  });
+
+  return { values, connectorFor: scoped, close: () => scoped.closeAll() };
+}
+
+/**
+ * `--set key=value` into a map, refusing anything that is not a pair.
+ *
+ * A flag given once arrives as a string and twice as an array, which is the
+ * parser's shape rather than a choice here.
+ */
+export function parseSet(input: readonly string[] | string | undefined): Record<string, string> {
+  const given = input === undefined ? [] : typeof input === 'string' ? [input] : input;
+  const values: Record<string, string> = {};
+
+  for (const entry of given) {
+    const at = entry.indexOf('=');
+    if (at <= 0) throw new Error(`--set wants key=value, and got "${entry}".`);
+    values[entry.slice(0, at)] = entry.slice(at + 1);
+  }
+
+  return values;
+}

package/src/cli/commands/knowledge/index.ts

@@ -74,10 +74,17 @@ export async function knowledgeShow(flags: KnowledgeFlags): Promise<void> {
     const selection = ` --profile ${runtime.resolution.profile} --target ${runtime.target}`;
     const skills = (await runtime.skills.list()).length;
     const memory = (await runtime.storage.list(`${KNOWLEDGE_LAYOUT.memory}/`)).length;
+    const entities = (await runtime.storage.list(`${KNOWLEDGE_LAYOUT.entities}/`)).length;
     const where = runtime.knowledge?.describe;
 
     if (flags.json) {
-      print(JSON.stringify({ target: runtime.target, where: where ?? 'local', memory, skills }, null, 2));
+      print(
+        JSON.stringify(
+          { target: runtime.target, where: where ?? 'local', memory, skills, entities },
+          null,
+          2,
+        ),
+      );
       return;
     }
 
@@ -96,6 +103,16 @@ export async function knowledgeShow(flags: KnowledgeFlags): Promise<void> {
         where ? `${where}/${KNOWLEDGE_LAYOUT.skills}` : layout.skills(profile),
         style.dim(`${skills} file${skills === 1 ? '' : 's'}`),
       ],
+      // The count includes the derived `_index.json`, deliberately: it is a
+      // file in that directory and it is committed with the rest, so a number
+      // that quietly excluded it would not match what a person sees there.
+      [
+        '  entities',
+        where
+          ? `${where}/${KNOWLEDGE_LAYOUT.entities}`
+          : `${layout.blobs(profile)}/${KNOWLEDGE_LAYOUT.entities}`,
+        style.dim(`${entities} file${entities === 1 ? '' : 's'}`),
+      ],
     ]);
 
     print('');
@@ -266,8 +283,9 @@ async function useLocal(flags: KnowledgeFlags): Promise<void> {
       const moved = await moveOut(repository, knowledge, local.storage, local.skills);
       print(
         ok(
-          `wrote back ${moved.memory} memory entr${moved.memory === 1 ? 'y' : 'ies'} and ` +
-            `${moved.skills} skill file${moved.skills === 1 ? '' : 's'}`,
+          `wrote back ${moved.memory} memory entr${moved.memory === 1 ? 'y' : 'ies'}, ` +
+            `${moved.skills} skill file${moved.skills === 1 ? '' : 's'} and ` +
+            `${moved.entities} entity file${moved.entities === 1 ? '' : 's'}`,
         ),
       );
     }
@@ -275,7 +293,7 @@ async function useLocal(flags: KnowledgeFlags): Promise<void> {
     await writeBlock(runtime.config, runtime.resolution.workspaceRoot, undefined);
 
     print('');
-    print(ok('memory and skills are back on this target\'s own storage'));
+    print(ok('memory, skills and entities are back on this target\'s own storage'));
     print(
       style.dim(
         `  ${knowledge.repo} still holds everything — it is version control, so nothing was removed from it.`,

package/src/cli/commands/knowledge/migrate.ts

@@ -1,4 +1,10 @@
-import { ConfigError, KNOWLEDGE_LAYOUT, knowledgeRoot, type KnowledgeConfig } from '#profile';
+import {
+  ConfigError,
+  KNOWLEDGE_LAYOUT,
+  knowledgeRoot,
+  type KnowledgeArea,
+  type KnowledgeConfig,
+} from '#profile';
 import type { BlobStore } from '#stores/blobs';
 import { commitFiles, type CommitFile } from '#deployments/adapters/github-commit.ts';
 import type { GithubRepository } from '#deployments/adapters/github-repo.ts';
@@ -24,10 +30,31 @@ export interface Movable {
   readonly key: string;
   /** Where it goes in the repository. */
   readonly path: string;
-  readonly area: 'memory' | 'skills';
+  readonly area: KnowledgeArea;
   readonly data: Uint8Array;
 }
 
+/**
+ * Where each area lives locally, as one table.
+ *
+ * Two of the three are prefixes inside the profile's blob root and the third is
+ * a store of its own, and that asymmetry was written out three times before —
+ * once per direction — which is three places to forget a fourth area. Stating
+ * it once means `localContents`, `removeLocal` and `moveOut` each became a loop
+ * over this rather than a branch on a literal.
+ */
+type LocalArea = { readonly store: BlobStore; readonly prefix: string };
+
+function localAreas(storage: BlobStore, skills: BlobStore): Record<KnowledgeArea, LocalArea> {
+  return {
+    memory: { store: storage, prefix: `${KNOWLEDGE_LAYOUT.memory}/` },
+    skills: { store: skills, prefix: '' },
+    entities: { store: storage, prefix: `${KNOWLEDGE_LAYOUT.entities}/` },
+  };
+}
+
+const AREAS = ['memory', 'skills', 'entities'] as const;
+
 /**
  * Everything this profile has stored locally, ready to move.
  *
@@ -42,30 +69,19 @@ export async function localContents(
   skills: BlobStore,
   knowledge: KnowledgeConfig,
 ): Promise<Movable[]> {
+  const areas = localAreas(storage, skills);
   const found: Movable[] = [];
-  const prefix = `${KNOWLEDGE_LAYOUT.memory}/`;
-
-  for (const entry of await storage.list(prefix)) {
-    const data = await storage.get(entry.key);
-    if (data === null) continue; // Listed then deleted; not worth failing over.
-    const key = entry.key.slice(prefix.length);
-    found.push({
-      key,
-      area: 'memory',
-      path: `${knowledgeRoot(knowledge, 'memory')}/${key}`,
-      data,
-    });
-  }
 
-  for (const entry of await skills.list()) {
-    const data = await skills.get(entry.key);
-    if (data === null) continue;
-    found.push({
-      key: entry.key,
-      area: 'skills',
-      path: `${knowledgeRoot(knowledge, 'skills')}/${entry.key}`,
-      data,
-    });
+  for (const area of AREAS) {
+    const { store, prefix } = areas[area];
+
+    for (const entry of await store.list(prefix)) {
+      const data = await store.get(entry.key);
+      if (data === null) continue; // Listed then deleted; not worth failing over.
+
+      const key = entry.key.slice(prefix.length);
+      found.push({ key, area, path: `${knowledgeRoot(knowledge, area)}/${key}`, data });
+    }
   }
 
   return found;
@@ -115,9 +131,11 @@ export async function removeLocal(
   skills: BlobStore,
   movable: readonly Movable[],
 ): Promise<void> {
+  const areas = localAreas(storage, skills);
+
   for (const item of movable) {
-    if (item.area === 'memory') await storage.delete(`${KNOWLEDGE_LAYOUT.memory}/${item.key}`);
-    else await skills.delete(item.key);
+    const { store, prefix } = areas[item.area];
+    await store.delete(`${prefix}${item.key}`);
   }
 }
 
@@ -135,24 +153,19 @@ export async function moveOut(
   knowledge: KnowledgeConfig,
   storage: BlobStore,
   skills: BlobStore,
-): Promise<{ memory: number; skills: number }> {
+): Promise<Record<KnowledgeArea, number>> {
   const { entries } = await repository.entries();
-  const roots = {
-    memory: `${knowledgeRoot(knowledge, 'memory')}/`,
-    skills: `${knowledgeRoot(knowledge, 'skills')}/`,
-  } as const;
-
-  const counts = { memory: 0, skills: 0 };
+  const areas = localAreas(storage, skills);
+  const counts: Record<KnowledgeArea, number> = { memory: 0, skills: 0, entities: 0 };
 
   for (const entry of entries.values()) {
-    for (const area of ['memory', 'skills'] as const) {
-      if (!entry.path.startsWith(roots[area])) continue;
-
-      const key = entry.path.slice(roots[area].length);
-      const data = await repository.blob(entry.sha);
+    for (const area of AREAS) {
+      const root = `${knowledgeRoot(knowledge, area)}/`;
+      if (!entry.path.startsWith(root)) continue;
 
-      if (area === 'memory') await storage.put(`${KNOWLEDGE_LAYOUT.memory}/${key}`, data);
-      else await skills.put(key, data);
+      const key = entry.path.slice(root.length);
+      const { store, prefix } = areas[area];
+      await store.put(`${prefix}${key}`, await repository.blob(entry.sha));
 
       counts[area] += 1;
     }
@@ -161,14 +174,19 @@ export async function moveOut(
   return counts;
 }
 
-/** `12 skills and 47 memory entries`, or whichever half of that is non-zero. */
+/** `12 skills and 47 memory entries`, or whichever parts of that are non-zero. */
 export function summarise(movable: readonly Movable[]): string {
-  const skills = movable.filter((item) => item.area === 'skills').length;
-  const memory = movable.length - skills;
+  const count = (area: KnowledgeArea) => movable.filter((item) => item.area === area).length;
+  const skills = count('skills');
+  const memory = count('memory');
+  const entities = count('entities');
 
+  // Skills and memory keep their existing wording and their existing order: a
+  // third clause is an addition to this sentence, not a rewrite of it.
   const parts = [
     ...(skills > 0 ? [`${skills} skill${skills === 1 ? '' : 's'}`] : []),
     ...(memory > 0 ? [`${memory} memory entr${memory === 1 ? 'y' : 'ies'}`] : []),
+    ...(entities > 0 ? [`${entities} entit${entities === 1 ? 'y' : 'ies'}`] : []),
   ];
   return parts.length === 0 ? 'nothing' : parts.join(' and ');
 }

package/src/cli/commands/operate/tools.ts

@@ -154,7 +154,7 @@ interface Surface {
  * `tools` as a count, matching `/reload` and `connect`; the names beside it.
  *
  * One key, one meaning. `ReloadResult.tools` and `PublishOutcome.tools` are both
- * numbers, and the count is what `docs/connect.md` tells an operator to compare
+ * numbers, and the count is what `https://lanes.sh/docs/link/connect` tells an operator to compare
  * against their client — shipping the same key here as an array would make
  * `.tools > 5` true for a single tool.
  */