@lanes-sh/link 0.2.2 → 0.3.0

package/src/profile/index.ts

@@ -19,11 +19,21 @@ export {
   type Config,
   type ConnectionConfig,
   type DeployConfig,
+  type IdentityEntry,
   type PolicyRuleConfig,
   type TargetConfig,
   type WorkspaceConfig,
 } from './schema.ts';
 
+export {
+  KNOWLEDGE_LAYOUT,
+  knowledgeRoot,
+  knowledgeTargetSchema,
+  parseRepository,
+  type KnowledgeArea,
+  type KnowledgeConfig,
+} from './knowledge.ts';
+
 export {
   ConfigError,
   loadConfigFile,
@@ -41,10 +51,10 @@ export {
 
 export {
   WORKSPACE_FILE,
-  describeSelection,
   installRoot,
   listProfiles,
   loadProfileConfig,
+  noProfileNamed,
   profilePath,
   readWorkspace,
   resolveSelection,
@@ -52,10 +62,9 @@ export {
   workspacePath,
 } from './workspace.ts';
 export {
-  TARGET_ENV,
-  askedTarget,
-  resolveDeployTarget,
-  resolveTarget,
+  LEGACY_TARGET_ENV,
+  noTargetNamed,
+  requireTarget,
   undeclaredTarget,
 } from './targets.ts';
 export {
@@ -65,6 +74,7 @@ export {
   writeWorkspaceFile,
 } from './files.ts';
 export {
+  type ProfileSelection,
   type Resolution,
   type ResolveOptions,
 } from './workspace.ts';

package/src/profile/knowledge.ts

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+import { credentialRef } from './primitives.ts';
+
+/**
+ * Where a profile's memory and skills live, when that is not where everything
+ * else lives.
+ *
+ * A target's `storage:` block names one backend for everything a profile holds
+ * — runtime state, the audit log, memory entries, skills, cached attachments.
+ * That is right for most of it and wrong for two: state and the log are
+ * artefacts of one installation, and memory entries and skills are documents
+ * the owner wrote. Documents want history, review, and to be readable from more
+ * than one machine, and the backend that suits an object nobody reads is not
+ * the backend that suits those.
+ *
+ * So this block moves exactly those two, and it is the whole of what it can
+ * move. There is no `credentials` or `vault` value here and there will not be:
+ * a repository is a place to publish, and those two hold the material whose
+ * entire value is that it is not published (`docs/detailed/security.md`). The
+ * exclusion is structural — a field that does not exist cannot be set by
+ * accident, by a flag, or by an operator following an example.
+ *
+ * `adapter` is an enum of one, the same shape `vaultTargetSchema` uses, so a
+ * second host is a case rather than a schema rewrite.
+ *
+ * Absent means what has always happened, which is why every field that could
+ * carry a default does. A profile written before this block existed loads
+ * unchanged and stores its memory and skills exactly where it did.
+ *
+ * ADR-041.
+ */
+
+/**
+ * `owner/name`, as GitHub spells it everywhere a person types one.
+ *
+ * A URL is deliberately not accepted. The browser URL, the SSH remote, and this
+ * are three spellings of one value, and a schema that takes all three has to
+ * normalise them somewhere — at which point the file no longer says what the
+ * operator wrote. The CLI accepts a pasted URL and reduces it to this before
+ * writing, which puts the leniency where a person is typing rather than in the
+ * contract.
+ */
+const repository = z
+  .string()
+  .regex(
+    /^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9._-]+$/,
+    'must be "owner/name" — not a URL, and not a local path',
+  );
+
+/**
+ * A directory inside the repository, for one that holds other things too.
+ *
+ * Normalised to no leading or trailing slash so `knowledge`, `/knowledge` and
+ * `knowledge/` are one prefix rather than three key spaces that look identical
+ * in a diff and address different objects.
+ */
+const repositoryPath = z
+  .string()
+  .refine((value) => !value.split('/').includes('..'), {
+    message: 'must not contain ".." — it is a prefix inside the repository, not a path to walk',
+  })
+  .transform((value) => value.replace(/^\/+/, '').replace(/\/+$/, ''));
+
+export const knowledgeTargetSchema = z.object({
+  adapter: z.literal('github'),
+  repo: repository,
+  /**
+   * Defaults at open time rather than here, to the repository's own default
+   * branch. Writing `main` into every generated config would be a guess, and a
+   * wrong one for anybody whose default is still `master` — a guess that then
+   * fails as "branch not found" rather than as "you did not say".
+   */
+  branch: z.string().min(1).optional(),
+  path: repositoryPath.optional(),
+  /**
+   * A reference, never the token.
+   *
+   * Its own ref rather than a reuse of the `github` provider connection's,
+   * which holds a token for GitHub's MCP server. That one needs Contents:
+   * *read*; this one needs Contents: *write*, has a different lifetime, and
+   * should be revocable on its own — revoking an MCP connection must not
+   * silently empty somebody's memory.
+   */
+  token_ref: credentialRef.default('knowledge/token'),
+});
+
+export type KnowledgeConfig = z.infer<typeof knowledgeTargetSchema>;
+
+/**
+ * Where each area sits inside the repository.
+ *
+ * Two directories, named after the two things that move. `memory` is also the
+ * memory provider's own blob namespace — the prefix core scopes it into under
+ * the profile's blob root — which is why the same word does both jobs: the
+ * route that redirects it and the directory it lands in are the same fact, and
+ * spelling them separately is how they would come to disagree.
+ *
+ * Declared here, beside the schema, so the runtime that opens these stores and
+ * the command that migrates into them read one definition.
+ */
+export const KNOWLEDGE_LAYOUT = {
+  memory: 'memory',
+  skills: 'skills',
+} as const;
+
+export type KnowledgeArea = keyof typeof KNOWLEDGE_LAYOUT;
+
+/** The directory one area occupies, under the profile's optional path prefix. */
+export function knowledgeRoot(knowledge: KnowledgeConfig, area: KnowledgeArea): string {
+  const directory = KNOWLEDGE_LAYOUT[area];
+  return knowledge.path ? `${knowledge.path}/${directory}` : directory;
+}
+
+/** `owner/name`, out of whatever a person pasted. Null when it is not one. */
+export function parseRepository(given: string): string | null {
+  const trimmed = given
+    .trim()
+    .replace(/^https?:\/\/(?:www\.)?github\.com\//i, '')
+    .replace(/^(?:ssh:\/\/)?git@[^:]+[:/]/i, '')
+    .replace(/\.git$/i, '')
+    .replace(/\/+$/, '');
+
+  return repository.safeParse(trimmed).success ? trimmed : null;
+}

package/src/profile/load.ts

@@ -114,11 +114,9 @@ function assertReferentialIntegrity(config: Config, source: string): void {
   if (targetNames.size === 0) {
     problems.push('targets: at least one target must be declared');
   }
-  if (!targetNames.has(config.instance.default_target)) {
-    problems.push(
-      `instance.default_target: "${config.instance.default_target}" is not a declared target (have: ${[...targetNames].join(', ') || 'none'})`,
-    );
-  }
+  // `instance.default_target` is deliberately not checked. Nothing reads it
+  // (ADR-037), so validating it would be validating a comment — and failing
+  // `check` on a stale value would teach that the key still matters.
 
   // Only what holds for every platform. What one platform needs and the next
   // has no concept of — a GCP project, an AWS role ARN — is refused by the
@@ -146,6 +144,20 @@ function assertReferentialIntegrity(config: Config, source: string): void {
     connectionKeys.add(key);
   });
 
+  // Same reason as a duplicate connection: two entries with the same kind and
+  // value cannot both be meant, and the one that loses is invisible. It matters
+  // more here than it looks, because the two would usually differ only in their
+  // `note` — so the discarded one is precisely the guidance someone wrote down
+  // to stop an agent picking wrong.
+  const identityKeys = new Set<string>();
+  config.identity.forEach((entry, index) => {
+    const key = `${entry.kind}=${entry.value}`;
+    if (identityKeys.has(key)) {
+      problems.push(`identity[${index}]: duplicate entry "${entry.kind}: ${entry.value}"`);
+    }
+    identityKeys.add(key);
+  });
+
   const checkRules = (rules: readonly PolicyRuleConfig[], field: 'allow' | 'deny'): void => {
     rules.forEach((rule, index) => {
       const where = `policy.${field}[${index}]`;

package/src/profile/primitives.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 
 /**
- * The three string shapes the config contract is built out of.
+ * The four string shapes the config contract is built out of.
  *
  * Their own file because more than one schema module needs them, and the
  * alternative was either a circular import or a second copy of a regex that
@@ -43,3 +43,26 @@ export const capabilityPattern = z
     /^(?:\*|[a-z][a-z0-9_]*\.(?:\*|[A-Za-z0-9][A-Za-z0-9_-]*(?:\.[A-Za-z0-9][A-Za-z0-9_-]*)*(?:\.\*)?))$/,
     'must be "*", "gmail.*", "gmail.users.*", or "gmail.users.drafts.send"',
   );
+
+/**
+ * A browser origin, exactly — scheme, host, and port, with nothing after it. Or
+ * `*`, which is what an absent list means anyway and is accepted so that saying
+ * it explicitly is not an error.
+ *
+ * Checked by round trip rather than by a regex, because `URL` already knows what
+ * an origin is and the failure this catches is a trailing slash or a path that
+ * looks harmless and matches nothing: a browser sends `Origin: https://x.example`
+ * and a configured `https://x.example/` would compare unequal, silently refusing
+ * the origin its owner believed they had allowed.
+ */
+export const browserOrigin = z.string().refine(
+  (value) => {
+    if (value === '*') return true;
+    try {
+      return new URL(value).origin === value;
+    } catch {
+      return false;
+    }
+  },
+  'must be "*" or an origin with no trailing slash or path, e.g. "https://chat.example"',
+);

package/src/profile/schema.ts

@@ -1,6 +1,8 @@
 import { z } from 'zod';
-import { capabilityPattern, credentialRef, identifier } from './primitives.ts';
+import { browserOrigin, capabilityPattern, credentialRef, identifier } from './primitives.ts';
 import { authorizationSchema } from './authorization.ts';
+import { identitySchema } from './identity.ts';
+import { knowledgeTargetSchema } from './knowledge.ts';
 
 /**
  * Configuration is declarative desired state. This file is the source of truth
@@ -214,6 +216,15 @@ export const targetSchema = z
     audit: auditTargetSchema.optional(),
     storage: storageTargetSchema,
     vault: vaultTargetSchema.optional(),
+    /**
+     * Memory and skills, somewhere other than `storage` above.
+     *
+     * Optional and absent by default, so every profile written before it keeps
+     * storing both exactly where it did. See `knowledge.ts` for why these two
+     * are separable from the rest and why the credential store and the vault
+     * are not.
+     */
+    knowledge: knowledgeTargetSchema.optional(),
     deploy: deployTargetSchema.optional(),
     /** @deprecated Write `deploy` with `platform: cloudrun`. */
     cloudrun: legacyCloudRunSchema.optional(),
@@ -313,7 +324,22 @@ export const configSchema = z.object({
 
   instance: z.object({
     profile: identifier,
-    default_target: z.string().min(1),
+    /**
+     * @deprecated Parsed, never read. See ADR-037.
+     *
+     * Every command names its target on the command line now, so nothing
+     * consults this. It stays *declared* rather than being dropped, and that is
+     * the whole point: an undeclared key is stripped silently by the schema,
+     * which would leave `check` and `doctor` with nothing to report and an
+     * operator staring at a line they reasonably believe still selects
+     * something. Declaring it is what lets them be told it is inert.
+     *
+     * Optional, so a profile written today needs no such line, and unvalidated,
+     * so a stale value naming a target that no longer exists is harmless rather
+     * than a failure on a key nothing reads. The `database:` note above records
+     * the same decision for the same reason.
+     */
+    default_target: z.string().min(1).optional(),
     port: z.number().int().min(1).max(65535).default(7337),
     /**
      * Loopback by default. Binding elsewhere is possible but the server
@@ -334,6 +360,15 @@ export const configSchema = z.object({
        * get one. Omitting it leaves every existing profile behaving identically.
        */
       authorization: authorizationSchema.optional(),
+      /**
+       * Browser origins that may call a *deployment's* MCP endpoint. Absent
+       * means `*`, so naming any is a narrowing and nothing needs setting.
+       *
+       * A deployment only, and this cannot widen that: a loopback endpoint
+       * refuses every cross-origin request and must keep doing so. Why the
+       * default is a wildcard is `src/server/cors.ts` and ADR-040.
+       */
+      allowed_origins: z.array(browserOrigin).optional(),
     })
     .default({ mode: 'bearer', token_ref: 'profile/token' }),
 
@@ -353,6 +388,13 @@ export const configSchema = z.object({
    */
   connections: z.array(connectionSchema).default([]),
   policy: policySchema.default({ allow: [], deny: [] }),
+
+  /**
+   * Who the owner is, for anything written as them. Optional and additive, so
+   * every profile written before it keeps loading unchanged — the same reasoning
+   * as `auth.authorization` above, and the reason `contract` does not move.
+   */
+  identity: identitySchema.default([]),
 });
 
 export type Config = z.infer<typeof configSchema>;
@@ -361,7 +403,8 @@ export type PolicyRuleConfig = z.infer<typeof policyRuleSchema>;
 export type TargetConfig = z.infer<typeof targetSchema>;
 export type DeployConfig = z.infer<typeof deployTargetSchema>;
 export type AuthorizationConfig = z.infer<typeof authorizationSchema>;
-export { authorizationSchema };
+export { authorizationSchema, identitySchema };
+export type { IdentityEntry } from './identity.ts';
 
 /** The workspace file: `lanes-link.yaml`, alongside a `profiles/` directory. */
 export const workspaceSchema = z.object({

package/src/profile/targets.ts

@@ -6,147 +6,107 @@ import type { Config } from './schema.ts';
  *
  * A target names an adapter set — where credentials are kept and where bytes
  * go — and choosing one is a different subject from finding the workspace and
- * the profile, which is why it is a different file. `workspace.ts` reached the
- * size budget holding both, and the budget's job is to say which of the two
- * things a file is doing should leave.
+ * the profile, which is why it is a different file.
  *
- * The order is `--target`, then `LANES_LINK_TARGET`, then
- * `instance.default_target`. `deploy` resolves it differently and deliberately;
- * see `resolveDeployTarget`.
+ * **`--target`, or the command does not run** (ADR-037). There is no fallback:
+ * not `LANES_LINK_TARGET`, not `instance.default_target`. Both are still
+ * parsed, so no existing config file has to change, and neither is read.
+ *
+ * The chain this replaces resolved `--target`, then the variable, then the key,
+ * and printed which of the three it landed on. What that bought was one flag
+ * saved per command. What it cost was that an *ignored* flag still produced a
+ * working command — `profile add --target cloud` dropped the flag on the floor
+ * and the next command carried on from a different source, so the mistake
+ * surfaced one command later with nothing connecting it to its cause. A
+ * resolver with nowhere to fall back to cannot fail that way.
  */
 
-/** The variable that names a target for every command in a shell. */
-export const TARGET_ENV = 'LANES_LINK_TARGET';
-
 /**
- * The target somebody asked for, before the config gets a say.
- *
- * Split out because two callers need this precedence and must not disagree
- * about it: `resolveSelection` records a provisional answer for `announce`
- * before any config is loaded, and `resolveTarget` settles it afterwards. While
- * the flag was the only source, both could spell it `targetFlag ?? …` and stay
- * accidentally correct. With a second source, one of them learning about it and
- * the other not is a line reading `config-default` beside a target the
- * environment chose — which is the one line that exists to prevent exactly that.
+ * The target this command named, checked against what the profile declares.
  *
- * Returns no target rather than a default: what an unanswered question falls
- * back to is `instance.default_target`, and that is the config's to supply.
+ * `allowUndeclared` is for the one command whose job is to create the target it
+ * was given — `deploy`, on a first run. Every other command naming a target that
+ * does not exist has made a typo, and the list of what does exist is the useful
+ * answer.
  */
-export function askedTarget(
+export function requireTarget(
+  config: Config,
   targetFlag: string | undefined,
-  env: Record<string, string | undefined>,
-): { target: string | undefined; source: 'flag' | 'environment' | undefined } {
-  if (targetFlag) return { target: targetFlag, source: 'flag' };
+  options: { allowUndeclared?: boolean; profile?: string } = {},
+): string {
+  if (!targetFlag) throw noTargetNamed(config, options.profile);
 
-  const fromEnv = env[TARGET_ENV];
-  if (fromEnv) return { target: fromEnv, source: 'environment' };
+  if (options.allowUndeclared !== true && !(targetFlag in config.targets)) {
+    throw undeclaredTarget(targetFlag, config, options.profile);
+  }
 
-  return { target: undefined, source: undefined };
+  return targetFlag;
 }
 
 /**
- * The refusal for a target that is not in the file, in one spelling.
+ * The refusal for a command that named no target.
  *
- * It was two — here and in the CLI's `openSecretStoreFor` — which is one more
- * than a sentence naming the available targets survives: the copies drift the
- * moment either learns something the other does not. This one knows about
- * `LANES_LINK_TARGET`, and that is precisely the knowledge a copy would lack —
- * an exported typo otherwise fails every command in the shell with a message
- * that reads as a problem with the config file.
+ * It lists the targets with their adapters, because "which one" is the question
+ * being asked and the adapter set is what distinguishes them. It also reports
+ * the two things that used to answer this and no longer do — an exported
+ * variable and the key still sitting in the file — since an operator looking at
+ * either has every reason to believe it is still working.
  */
-export function undeclaredTarget(
-  target: string,
+export function noTargetNamed(
   config: Config,
-  source?: 'flag' | 'environment' | 'config-default',
+  profile?: string,
+  env: Record<string, string | undefined> = process.env as Record<string, string | undefined>,
 ): ConfigError {
-  const have = Object.keys(config.targets).join(', ') || 'none';
+  const names = Object.keys(config.targets);
+  const whose = profile ? ` by profile "${profile}"` : '';
+
+  const rows = names
+    .map((name) => {
+      const declared = config.targets[name]!;
+      const deployed = declared.deploy ? '  deployed' : '';
+      return `    ${name}    ${declared.credentials.adapter}  ${declared.storage.adapter}${deployed}`;
+    })
+    .join('\n');
+
+  const stale = env[LEGACY_TARGET_ENV];
+  const inert = config.instance.default_target;
+
   return new ConfigError(
-    `Target "${target}" is not declared in this profile (have: ${have})` +
-      (source === 'environment'
-        ? `\n${TARGET_ENV}=${target} is set in this shell — unset it, or pass --target.`
+    '--target is required. This command opens a target\'s stores, and nothing\n' +
+      'else selects one.\n\n' +
+      `  Targets declared${whose}\n${rows}\n` +
+      `\n  e.g. lanes link status --profile ${profile ?? '<name>'} --target ${names[0] ?? '<target>'}` +
+      (stale
+        ? `\n\n  ${LEGACY_TARGET_ENV}=${stale} is set in this shell and is no longer read.\n` +
+          '  Unset it, or pass --target.'
+        : '') +
+      (inert
+        ? `\n\n  instance.default_target: ${inert} is still in this profile. It is no longer\n` +
+          '  read either, and is safe to delete.'
         : ''),
   );
 }
 
 /**
- * Fill in the target once the profile's config has been loaded.
- *
- * Order: `--target`, then `LANES_LINK_TARGET`, then `instance.default_target`.
- * The middle one is the same bargain `LANES_LINK_PROFILE` already offers — a
- * shell's worth of commands without retyping a flag, somewhere `env` shows it.
+ * The variable that used to name a target, kept only to say it is ignored.
  *
- * `allowUndeclared` is for the one command whose job is to create the target it
- * was given — `deploy`, on a first run. Every other command naming a target that
- * does not exist has made a typo, and the list of what does exist is the useful
- * answer; refusing there is what stops `--target clod` opening the default one.
+ * Not read by anything that resolves. It exists so a refusal can name the thing
+ * an operator is looking at and reasonably believes is still working — which is
+ * the whole difference between "this stopped working" and "this stopped working
+ * and here is why".
  */
-export function resolveTarget(
-  config: Config,
-  targetFlag?: string,
-  options: {
-    allowUndeclared?: boolean;
-    env?: Record<string, string | undefined>;
-  } = {},
-): { target: string; source: 'flag' | 'environment' | 'config-default' } {
-  const env = options.env ?? (process.env as Record<string, string | undefined>);
-  const asked = askedTarget(targetFlag, env);
-
-  const target = asked.target ?? config.instance.default_target;
-  const source = asked.source ?? 'config-default';
-
-  if (options.allowUndeclared !== true && !(target in config.targets)) {
-    throw undeclaredTarget(target, config, source);
-  }
-  return { target, source };
-}
+export const LEGACY_TARGET_ENV = 'LANES_LINK_TARGET';
 
 /**
- * The target a deploy means, when nobody said.
- *
- * `--target cloud` was required on every deploy, and the reason was an accident:
- * an absent flag falls back to `instance.default_target`, which is `local` —
- * a target that by definition is not deployed anywhere. So the one command whose
- * subject is never ambiguous was the one command that made you say it, and the
- * default it would otherwise have taken was not merely unhelpful but wrong.
- *
- * The rule is what someone would say out loud: deploy the target that has a
- * deployment. One is the answer; none means the first run, which conventionally
- * creates `cloud` and is what every example in the docs names; several is a
- * genuine question, and asking beats rolling a revision to whichever came first
- * in a YAML mapping.
- *
- * `--target` still wins, which is how you deploy the second one.
+ * The refusal for a target that is not in the file, in one spelling.
  *
- * **`LANES_LINK_TARGET` is deliberately not read here.** It is the same kind of
- * answer as `instance.default_target` — a shell-wide "where do my commands
- * run" — and the paragraph above is why that kind of answer is the wrong one
- * for this question. It is also the only place where being wrong creates cloud
- * resources rather than an error: `deploy` is the one caller that passes
- * `allowUndeclared`, so an exported typo would not be refused, it would be
- * surveyed, written into the profile, and rolled out as a new service. An
- * environment variable must not be able to name a Cloud Run service into
- * existence. Say `--target`; `deploy` is rare enough to afford it.
+ * It was two — here and in the CLI's `openSecretStoreFor` — which is one more
+ * than a sentence naming the available targets survives: the copies drift the
+ * moment either learns something the other does not.
  */
-export const CONVENTIONAL_DEPLOY_TARGET = 'cloud';
-
-export function resolveDeployTarget(
-  config: Config,
-  targetFlag?: string,
-): { target: string; source: 'flag' | 'deployable' } {
-  if (targetFlag) return { target: targetFlag, source: 'flag' };
-
-  // `deploy` alone: the legacy `cloudrun:` spelling is normalised into it by the
-  // loader, so exactly one shape reaches here.
-  const deployable = Object.entries(config.targets)
-    .filter(([, declared]) => declared.deploy !== undefined)
-    .map(([name]) => name);
-
-  if (deployable.length > 1) {
-    throw new ConfigError(
-      `This profile declares ${deployable.length} deployable targets (${deployable.join(', ')}). ` +
-        'Name the one you mean with --target.',
-    );
-  }
+export function undeclaredTarget(target: string, config: Config, profile?: string): ConfigError {
+  const have = Object.keys(config.targets).join(', ') || 'none';
+  const whose = profile ? `profile "${profile}"` : 'this profile';
 
-  return { target: deployable[0] ?? CONVENTIONAL_DEPLOY_TARGET, source: 'deployable' };
+  return new ConfigError(`Target "${target}" is not declared by ${whose} (have: ${have})`);
 }