@lanes-sh/link 0.2.2 → 0.3.1

package/src/profile/index.ts

@@ -14,16 +14,28 @@
 export {
   SUPPORTED_CONTRACT,
   configSchema,
+  deploymentRecordSchema,
   workspaceSchema,
   type AuthorizationConfig,
   type Config,
   type ConnectionConfig,
   type DeployConfig,
+  type DeploymentRecord,
+  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,23 +53,28 @@ export {
 
 export {
   WORKSPACE_FILE,
-  describeSelection,
   installRoot,
   listProfiles,
   loadProfileConfig,
+  loadWorkspaceProfiles,
+  noProfileNamed,
   profilePath,
   readWorkspace,
   resolveSelection,
   resolveWorkspaceRoot,
+  targetsByName,
   workspacePath,
+  type LoadedProfile,
+  type WorkspaceProfiles,
 } from './workspace.ts';
 export {
-  TARGET_ENV,
-  askedTarget,
-  resolveDeployTarget,
-  resolveTarget,
+  LEGACY_TARGET_ENV,
+  noTargetInWorkspace,
+  noTargetNamed,
+  requireTarget,
   undeclaredTarget,
 } from './targets.ts';
+export { findDeployment, readDeployments, recordDeployment } from './deployments.ts';
 export {
   isRemoteWorkspace,
   readWorkspaceFile,
@@ -65,6 +82,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-039.
+       */
+      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,12 +403,48 @@ 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';
+
+/**
+ * Where a deployment lives — an index, not configuration.
+ *
+ * **Nothing resolves from this.** A target is still declared by the profile,
+ * and a command still acts on what the profile says. This exists because the
+ * profile file was the *only* record that a deployment existed, so rewriting
+ * one erased the sole pointer to a live service, a bucket holding every byte
+ * the endpoint remembered, and a credential store — none of which had gone
+ * anywhere. There was no command that could find them again.
+ *
+ * It lives in `lanes-link.yaml`, outside any profile, for exactly that reason:
+ * a record kept inside the thing it describes cannot survive the thing being
+ * lost. `lanes link sync targets` reads it, and reads it *only* to know where
+ * to look (ADR-044).
+ *
+ * Written by `deploy`, after an upload has succeeded — so it never names a
+ * workspace nothing was ever put in.
+ */
+export const deploymentRecordSchema = z.object({
+  target: identifier,
+  /** Where the deployed endpoint reads its config: `gs://bucket[/prefix]`. */
+  workspace: z.string().min(1),
+  /**
+   * Whose bearer token opens this endpoint (ADR-009).
+   *
+   * Recorded rather than inferred. One endpoint serves every profile in the
+   * bucket under one token, and which profile's token that is decides who gets
+   * in — the one question about a deployment that must not be guessed at.
+   */
+  primary: identifier.optional(),
+  last_deploy: z.string().optional(),
+});
 
 /** The workspace file: `lanes-link.yaml`, alongside a `profiles/` directory. */
 export const workspaceSchema = z.object({
   contract: z.number().int().positive(),
   default_profile: identifier.optional(),
+  deployments: z.array(deploymentRecordSchema).default([]),
 });
 
 export type WorkspaceConfig = z.infer<typeof workspaceSchema>;
+export type DeploymentRecord = z.infer<typeof deploymentRecordSchema>;