@fro.bot/systematic 3.37.0 → 3.38.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -3,6 +3,7 @@ import {
3
3
  parseFrontmatter,
4
4
  string,
5
5
  number,
6
+ opencodeUserConfigDir,
6
7
  AgentOverlaySchema,
7
8
  CategoryOverlaySchema,
8
9
  isRecord,
@@ -26,15 +27,15 @@ import {
26
27
  SEARCH_NOTICES,
27
28
  SEARCH_CONFIG_UNREADABLE_NOTE,
28
29
  runSearch
29
- } from "./index-1cj1mrpb.js";
30
+ } from "./index-ahm7y9zh.js";
30
31
 
31
32
  // src/index.ts
32
- import path8 from "path";
33
+ import path7 from "path";
33
34
  import { fileURLToPath } from "url";
34
35
 
35
36
  // src/lib/opencode-v1.ts
36
37
  import fs6 from "fs";
37
- import path6 from "path";
38
+ import path5 from "path";
38
39
 
39
40
  // src/lib/bootstrap.ts
40
41
  import fs from "fs";
@@ -177,7 +178,6 @@ function composeBootstrapContent(config, options) {
177
178
 
178
179
  // src/lib/config-handler.ts
179
180
  import os2 from "os";
180
- import path4 from "path";
181
181
 
182
182
  // src/lib/asset-plan.ts
183
183
  import fs4 from "fs";
@@ -956,7 +956,7 @@ function applyDiscoveredRouting(config, plan, reported) {
956
956
  function createConfigHandler(deps) {
957
957
  const { directory, bundledSkillsDir, bundledAgentsDir, bundledCommandsDir } = deps;
958
958
  const homeDir = deps.homeDir ?? os2.homedir();
959
- const opencodeConfigDir = deps.opencodeConfigDir ?? path4.join(homeDir, ".config/opencode");
959
+ const opencodeConfigDir = deps.opencodeConfigDir ?? opencodeUserConfigDir(homeDir);
960
960
  const opencodeConfigDirOverride = process.env.OPENCODE_CONFIG_DIR?.trim() ? process.env.OPENCODE_CONFIG_DIR : undefined;
961
961
  const reportedRouting = new Set;
962
962
  return async (config) => {
@@ -1160,7 +1160,7 @@ var installSearch = async ({
1160
1160
 
1161
1161
  // src/lib/skill-resolver.ts
1162
1162
  import fs5 from "fs";
1163
- import path5 from "path";
1163
+ import path4 from "path";
1164
1164
  import { pathToFileURL } from "url";
1165
1165
 
1166
1166
  // src/lib/skill-catalog.ts
@@ -1254,7 +1254,7 @@ ${raw}`;
1254
1254
  function buildSkillContentOutput(matchedSkill, argument) {
1255
1255
  const trimmedBody = extractSkillBody(matchedSkill.wrappedTemplate).trim();
1256
1256
  const body = argument === undefined ? trimmedBody : substituteSkillArguments(trimmedBody, argument);
1257
- const dir = path5.dirname(matchedSkill.skillFile);
1257
+ const dir = path4.dirname(matchedSkill.skillFile);
1258
1258
  const base = pathToFileURL(dir).href;
1259
1259
  const files = discoverSkillFiles(dir);
1260
1260
  const lines = [
@@ -1285,10 +1285,10 @@ function discoverSkillFiles(dir, limit = 10) {
1285
1285
  function handleEntry(entry, currentDir) {
1286
1286
  if (entry.isDirectory()) {
1287
1287
  if (!shouldSkipDirectory(entry.name)) {
1288
- recurse(path5.resolve(currentDir, entry.name));
1288
+ recurse(path4.resolve(currentDir, entry.name));
1289
1289
  }
1290
1290
  } else if (shouldIncludeFile(entry.name)) {
1291
- files.push(path5.resolve(currentDir, entry.name));
1291
+ files.push(path4.resolve(currentDir, entry.name));
1292
1292
  }
1293
1293
  }
1294
1294
  function recurse(currentDir) {
@@ -1507,10 +1507,10 @@ var getPackageVersion = (packageJsonPath) => {
1507
1507
  }
1508
1508
  };
1509
1509
  var createOpenCodeV1Hooks = async ({ client, directory }, { packageRoot }) => {
1510
- const bundledSkillsDir = path6.join(packageRoot, "skills");
1511
- const bundledAgentsDir = path6.join(packageRoot, "agents");
1512
- const bundledCommandsDir = path6.join(packageRoot, "commands");
1513
- const packageJsonPath = path6.join(packageRoot, "package.json");
1510
+ const bundledSkillsDir = path5.join(packageRoot, "skills");
1511
+ const bundledAgentsDir = path5.join(packageRoot, "agents");
1512
+ const bundledCommandsDir = path5.join(packageRoot, "commands");
1513
+ const packageJsonPath = path5.join(packageRoot, "package.json");
1514
1514
  let hasLoggedInit = false;
1515
1515
  let userOutputLimitSet = false;
1516
1516
  const skillOutputStore = createSkillOutputStore();
@@ -1601,7 +1601,7 @@ var createOpenCodeV1Hooks = async ({ client, directory }, { packageRoot }) => {
1601
1601
 
1602
1602
  // src/lib/opencode-v2.ts
1603
1603
  import os3 from "os";
1604
- import path7 from "path";
1604
+ import path6 from "path";
1605
1605
 
1606
1606
  // src/lib/opencode-v2-bootstrap.ts
1607
1607
  var BOOTSTRAP_ENTRY_KEY = "systematic.bootstrap";
@@ -2128,9 +2128,9 @@ function composeBootstrapOrNull(config, bundledSkillsDir) {
2128
2128
  function buildSnapshot(ctx, deps) {
2129
2129
  const { packageRoot } = deps;
2130
2130
  const homeDir = deps.homeDir ?? os3.homedir();
2131
- const opencodeConfigDir = deps.opencodeConfigDir ?? path7.join(homeDir, ".config/opencode");
2131
+ const opencodeConfigDir = deps.opencodeConfigDir ?? opencodeUserConfigDir(homeDir);
2132
2132
  const opencodeConfigDirOverride = process.env.OPENCODE_CONFIG_DIR?.trim() ? process.env.OPENCODE_CONFIG_DIR : undefined;
2133
- const bundledSkillsDir = path7.join(packageRoot, "skills");
2133
+ const bundledSkillsDir = path6.join(packageRoot, "skills");
2134
2134
  const projectDirectory = resolveProjectDirectory(ctx);
2135
2135
  if (projectDirectory === undefined) {
2136
2136
  reportDiagnostic("the host gave no project directory; loading user-level config only");
@@ -2149,8 +2149,8 @@ function buildSnapshot(ctx, deps) {
2149
2149
  nativeAgentNames: [],
2150
2150
  directory,
2151
2151
  bundledSkillsDir,
2152
- bundledAgentsDir: path7.join(packageRoot, "agents"),
2153
- bundledCommandsDir: path7.join(packageRoot, "commands"),
2152
+ bundledAgentsDir: path6.join(packageRoot, "agents"),
2153
+ bundledCommandsDir: path6.join(packageRoot, "commands"),
2154
2154
  homeDir,
2155
2155
  opencodeConfigDir,
2156
2156
  opencodeConfigDirOverride
@@ -2210,8 +2210,8 @@ function withoutGuardedAgents(snapshot) {
2210
2210
  }
2211
2211
 
2212
2212
  // src/index.ts
2213
- var __dirname2 = path8.dirname(fileURLToPath(import.meta.url));
2214
- var packageRoot = path8.resolve(__dirname2, "..");
2213
+ var __dirname2 = path7.dirname(fileURLToPath(import.meta.url));
2214
+ var packageRoot = path7.resolve(__dirname2, "..");
2215
2215
  var systematicPlugin = {
2216
2216
  id: "systematic",
2217
2217
  async setup(ctx) {
@@ -10,7 +10,7 @@ export interface ConfigHandlerDeps {
10
10
  bundledCommandsDir: string;
11
11
  /** Home directory for discovered-skill lookups. Defaults to `os.homedir()`; inject a temp dir in tests. */
12
12
  homeDir?: string;
13
- /** OpenCode global config directory override for discovered-skill lookups. Defaults to `<homeDir>/.config/opencode`. */
13
+ /** OpenCode global config directory override for discovered-skill lookups. Defaults to `$XDG_CONFIG_HOME/opencode` when set, else `<homeDir>/.config/opencode`. */
14
14
  opencodeConfigDir?: string;
15
15
  }
16
16
  /** Clear the once-per-process notice record and captured routing. For tests. */
@@ -402,6 +402,12 @@ export declare function createSystematicConfigSchema(opts: SystematicConfigSchem
402
402
  connect: z.ZodOptional<z.ZodObject<{
403
403
  allow_projects: z.ZodOptional<z.ZodArray<z.ZodString>>;
404
404
  groups: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
405
+ pins: z.ZodOptional<z.ZodArray<z.ZodObject<{
406
+ project: z.ZodString;
407
+ upstream: z.ZodString;
408
+ file: z.ZodString;
409
+ key: z.ZodString;
410
+ }, z.core.$strict>>>;
405
411
  }, z.core.$strict>>;
406
412
  disabled_skills: z.ZodDefault<z.ZodArray<z.ZodEnum<{
407
413
  [x: string]: string;
@@ -615,6 +621,12 @@ export declare const SystematicConfigSchema: z.ZodObject<{
615
621
  connect: z.ZodOptional<z.ZodObject<{
616
622
  allow_projects: z.ZodOptional<z.ZodArray<z.ZodString>>;
617
623
  groups: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
624
+ pins: z.ZodOptional<z.ZodArray<z.ZodObject<{
625
+ project: z.ZodString;
626
+ upstream: z.ZodString;
627
+ file: z.ZodString;
628
+ key: z.ZodString;
629
+ }, z.core.$strict>>>;
618
630
  }, z.core.$strict>>;
619
631
  disabled_skills: z.ZodDefault<z.ZodArray<z.ZodEnum<{
620
632
  [x: string]: string;
@@ -1,5 +1,5 @@
1
1
  import { CONFIG_PROTECTED_FIELD_PATHS, type ConfigProtectedFieldPath } from './config-protected-fields.js';
2
- import type { ConnectSettings } from './connect-config.js';
2
+ import { type ConnectSettings } from './connect-config.js';
3
3
  import { type RoutingTarget } from './routing-resolver.js';
4
4
  import { type SearchSchemaOutput } from './search-user-config.js';
5
5
  export interface BootstrapConfig {
@@ -5,13 +5,19 @@
5
5
  * limits have host-specific evidence.
6
6
  *
7
7
  * Import rule: this module may import only `jsonc-parser`, node builtins,
8
- * `search-bounded-read.ts` and `search-project-identity.ts` (both node
9
- * builtins only). It must never import zod, `config.ts`, `config-schema.ts` or
8
+ * `opencode-config-dir.ts`, `search-bounded-read.ts` and
9
+ * `search-project-identity.ts` (each node builtins only). It must never import zod, `config.ts`, `config-schema.ts` or
10
10
  * `search-user-config.ts`: the `ce:connect` helper bundles it, and any of those
11
11
  * would drag the config loader and zod into that bundle. `config-schema.ts`
12
12
  * imports the limits from here and tags the same block `trust:
13
13
  * 'project-or-higher'`; the dependency runs one way.
14
14
  *
15
+ * The block also holds `pins`: declared dependency pins, each saying that a
16
+ * project pins an upstream at the value under a key in a file. The reader only
17
+ * validates their shape and returns them; whether a pin matches a selected
18
+ * project, and what it resolves to, is decided at `begin`, never here. A pin
19
+ * never adds a project to the allow list.
20
+ *
15
21
  * The block also holds named `groups` of allow-list-form entries. A group
16
22
  * narrows a run to part of the allow list and never adds a project: nothing
17
23
  * here checks that a member is on the allow list; the selection step does,
@@ -27,11 +33,12 @@
27
33
  * unreadable block contributes no entries. A missing, unparseable, oversize
28
34
  * or non-regular file contributes none either. No failure can add an entry
29
35
  * the user did not write. The four layers merge, the allow lists by union and
30
- * the groups by name (a later layer replaces a same-named group whole), so a
31
- * layer that fails drops only its own entries and groups.
36
+ * the groups by name (a later layer replaces a same-named group whole) and
37
+ * the pins as a union deduplicated as written, so a layer that fails drops only
38
+ * its own entries, groups and pins.
32
39
  *
33
- * Warnings name config files and reasons, never an allow-list entry: an entry
34
- * is a project the user chose to expose, and a warning can reach logs and
40
+ * Warnings name config files and reasons, never an allow-list entry or a pin:
41
+ * an entry is a project the user chose to expose, and a warning can reach logs and
35
42
  * replies that the project is not allowed to see.
36
43
  */
37
44
  /** The allow list holds at most this many entries. */
@@ -44,25 +51,75 @@ export declare const MAX_CONNECT_CONFIG_BYTES: number;
44
51
  export declare const MAX_CONNECT_GROUPS = 32;
45
52
  /** A group name: lowercase letters, digits and hyphens, one to 64 characters, led by a letter or digit. */
46
53
  export declare const CONNECT_GROUP_NAME_PATTERN: RegExp;
54
+ /** One config layer holds at most this many pins. */
55
+ export declare const MAX_CONNECT_PINS = 64;
56
+ /** A pin's `file` is at most this many characters. */
57
+ export declare const MAX_PIN_FILE_LENGTH = 256;
58
+ /** A pin's `key` is at most this many characters. */
59
+ export declare const MAX_PIN_KEY_LENGTH = 256;
60
+ /**
61
+ * A pin's `file`: a repo-relative path in a narrow charset (letters, digits,
62
+ * `.`, `_`, `-` and `/`), with no leading slash and no `..` segment. It
63
+ * says nothing about whether the file exists or is safe to open; the pin reader
64
+ * contains the read.
65
+ */
66
+ export declare const PIN_FILE_PATTERN: RegExp;
67
+ /**
68
+ * `owner/repo`, shaped as GitHub allows and nothing else. The one rule for a
69
+ * repository that is printed into a command, put in an API path or recorded as
70
+ * provenance, so every `connect-*` module and the helper agree on it. It checks
71
+ * the shape only and keeps the case; it says nothing about whether the
72
+ * repository exists. It lives here, below `connect-repo-identity.ts` which
73
+ * re-exports it, so the pin guard can use it without an import cycle.
74
+ */
75
+ export declare function isGithubOwnerRepo(value: string): boolean;
76
+ /**
77
+ * A pin's `key`: one or more non-empty segments joined by single dots, at most
78
+ * `MAX_PIN_KEY_LENGTH` characters, no control character. Shape only: whether
79
+ * the key names anything in the file is the pin reader's question.
80
+ */
81
+ export declare function isPinKey(value: string): boolean;
47
82
  /** Group name to member list. A member has the form of an allow-list entry. */
48
83
  export type ConnectGroups = Record<string, string[]>;
84
+ /**
85
+ * A declared dependency pin: `project` pins `upstream` at the value found
86
+ * under `key` in `file`. `project` has the form of an allow-list entry and is
87
+ * matched, not resolved, at `begin`.
88
+ */
89
+ export interface ConnectPin {
90
+ readonly project: string;
91
+ readonly upstream: string;
92
+ readonly file: string;
93
+ readonly key: string;
94
+ }
49
95
  export interface ConnectSettings {
50
96
  allow_projects: string[];
51
97
  groups?: ConnectGroups;
98
+ pins?: ConnectPin[];
52
99
  }
53
100
  export type ConnectBlockValidation = {
54
101
  readonly ok: true;
55
102
  readonly allowProjects: string[];
56
103
  readonly groups: ConnectGroups;
104
+ readonly pins: ConnectPin[];
57
105
  } | {
58
106
  readonly ok: false;
59
107
  };
108
+ /**
109
+ * The union of pin lists in the order given, deduplicated as written: two
110
+ * entries are one only when all four values are equal, and the first one
111
+ * seen keeps its place. It decides nothing about conflicts; two entries that
112
+ * share a project, upstream and key but name different files both survive.
113
+ */
114
+ export declare function unionPins(lists: readonly (readonly ConnectPin[] | undefined)[]): ConnectPin[];
60
115
  /**
61
116
  * Validate a `connect` block with plain guards. The block is valid when it is
62
- * an object whose only keys, if any, are `allow_projects` and `groups`.
117
+ * an object whose only keys, if any, are `allow_projects`, `groups` and
118
+ * `pins`.
63
119
  * `allow_projects` holds at most `MAX_ALLOW_PROJECTS` non-empty strings of at
64
120
  * most `MAX_ALLOW_PROJECT_LENGTH` characters. `groups` maps names to member
65
- * lists as `readGroups` describes. The zod schema in `config-schema.ts`
121
+ * lists as `readGroups` describes. `pins` holds at most `MAX_CONNECT_PINS`
122
+ * entries as `readPin` describes. The zod schema in `config-schema.ts`
66
123
  * accepts and rejects the same values; a test pins the two together.
67
124
  */
68
125
  export declare function validateConnectBlock(value: unknown): ConnectBlockValidation;
@@ -107,6 +164,14 @@ export interface ConnectAllowListLoad {
107
164
  * group whole. A member is not checked against the allow list here.
108
165
  */
109
166
  readonly groups: Readonly<Record<string, readonly string[]>>;
167
+ /**
168
+ * The readable layers' pins in layer order, deduplicated as written: two
169
+ * entries are one only when all four values are equal. No grouping and no
170
+ * conflict logic here; the helper decides both after it has resolved each
171
+ * pin's project. A pin is shape-checked only: its project is not checked
172
+ * against the allow list and a pin never adds a project to it.
173
+ */
174
+ readonly pins: readonly ConnectPin[];
110
175
  /** Some layer's file or block could not be read and contributed nothing. */
111
176
  readonly unreadable: boolean;
112
177
  /** One line per problem. They name files and reasons, never an allow-list entry. */
@@ -164,6 +229,12 @@ export interface ResolvedAllowList {
164
229
  readonly resolved: ReadonlyArray<{
165
230
  readonly entry: string;
166
231
  readonly mainRoot: string;
232
+ /**
233
+ * The later spellings of the same project that collapsed into this entry,
234
+ * as written, in order. Absent when there are none. A pin may name its
235
+ * project by any of them.
236
+ */
237
+ readonly aliases?: readonly string[];
167
238
  }>;
168
239
  readonly unmatched: ReadonlyArray<{
169
240
  readonly entry: string;
@@ -172,7 +243,8 @@ export interface ResolvedAllowList {
172
243
  }
173
244
  /**
174
245
  * Resolve every entry. Two entries that name one project collapse into the
175
- * first; a later duplicate is neither resolved nor unmatched.
246
+ * first; a later duplicate is neither resolved nor unmatched, but its spelling
247
+ * is kept as an alias of the first.
176
248
  */
177
249
  export declare function resolveAllowList(entries: readonly string[], options?: AllowEntryOptions): ResolvedAllowList;
178
250
  export declare const CONNECT_HOSTS: readonly ['opencode-v1', 'opencode-v2', 'pi', 'claude-code'];
@@ -18,6 +18,7 @@
18
18
  * rendered as quoted evidence.
19
19
  */
20
20
  import { type ContainedRead, type InventoryFile, type InventoryRole } from './connect-evidence.js';
21
+ import { type PinNote } from './connect-pins.js';
21
22
  import type { CandidateRecord, CoverageRecord, Ledger } from './connect-state.js';
22
23
  /**
23
24
  * Where run state lives: `systematic/connect` under an absolute, non-empty
@@ -426,6 +427,8 @@ export interface DigestModel {
426
427
  readonly path: string;
427
428
  readonly cites: number;
428
429
  }>;
430
+ /** Why a declared dependency pin gave no hint line. Shown in the summary; never a reason to degrade. */
431
+ readonly pinNotes?: readonly PinNote[];
429
432
  }
430
433
  /** Strip control and format characters. Line breaks stay; tabs become a space. */
431
434
  export declare function sanitizeText(text: string): string;
@@ -515,6 +518,8 @@ export type Selection = {
515
518
  export interface SelectionProject {
516
519
  readonly entry: string;
517
520
  readonly mainRoot: string;
521
+ /** Later allow-list spellings of the same project, as written. */
522
+ readonly aliases?: readonly string[];
518
523
  }
519
524
  export type MemberResolution = {
520
525
  readonly status: 'resolved';
@@ -0,0 +1,131 @@
1
+ /**
2
+ * Dependency pins for `ce:connect`: the version a project pins an upstream at,
3
+ * read from the project's own files, and the hint lines `begin` renders from
4
+ * it.
5
+ *
6
+ * `resolvePins` turns declared pins into hint lines. A pin matches only a
7
+ * project the run has already selected and scanned, by an allow-list entry as
8
+ * written (any spelling that resolved to it) or by its resolved root; a path a pin declares itself is never resolved or
9
+ * opened. It reads nothing until a pin has matched a selected project and a
10
+ * selected checkout of the upstream. The line is a fixed template whose slots
11
+ * passed strict charsets, and it names projects by the roots the `begin`
12
+ * answer lists, never by name or key.
13
+ *
14
+ * `readPinValue` reads one pin value live from a project's working tree. The
15
+ * read is contained and bounded (`readContainedFile`: safe relative path, no
16
+ * symlink, size cap), parsed as JSON or JSONC, and walked by a dotted key
17
+ * path. The result is a plain string that passed `PIN_VALUE_PATTERN` or one
18
+ * fixed failure code. A failure never carries file content, a key, a value or
19
+ * a path, so a code is safe to show. The file is untrusted data: a value that
20
+ * fails the charset is rejected, never cleaned up.
21
+ *
22
+ * Import rule: node builtins, `jsonc-parser` and sibling connect modules only.
23
+ * Never zod, `config.ts` or `config-schema.ts`, because the `ce:connect`
24
+ * helper bundles this module. Never throws.
25
+ */
26
+ import { type ConnectPin } from './connect-config.js';
27
+ import { type TagAtHead } from './connect-repo-identity.js';
28
+ /**
29
+ * The shape of a pin value, and so of the version a rendered hint states: one
30
+ * leading letter or digit, then letters, digits, `.`, `_`, `+` and `-`, 64
31
+ * characters at most. It is `TAG_NAME_PATTERN` without the `/`: a tag may be
32
+ * `release/1.2`, but a pinned version names no path, and refusing the slash
33
+ * keeps a value from reading as one. Reject, do not sanitize.
34
+ */
35
+ export declare const PIN_VALUE_PATTERN: RegExp;
36
+ /** Why a pin value could not be read. The only text a failure carries. */
37
+ export type PinFailureCode = 'pin-file-missing' | 'pin-file-too-large' | 'pin-file-invalid' | 'pin-key-absent' | 'pin-value-invalid';
38
+ export type PinValueResult = {
39
+ readonly kind: 'ok';
40
+ readonly value: string;
41
+ } | {
42
+ readonly kind: 'failed';
43
+ readonly code: PinFailureCode;
44
+ };
45
+ /**
46
+ * Read the string at `key` in the JSON or JSONC file `file` under `root`.
47
+ *
48
+ * `root` must be a trusted real path. `file` is repo-relative and `key` is
49
+ * dotted segments with no array index. The working tree is read as it is:
50
+ * tracked status is not checked, so an untracked file works.
51
+ *
52
+ * - `pin-file-missing`: no such file, a directory, a symlink, a path outside
53
+ * the root, or a file that cannot be read.
54
+ * - `pin-file-too-large`: over the read cap.
55
+ * - `pin-file-invalid`: empty, malformed, or not UTF-8 JSONC.
56
+ * - `pin-key-absent`: the key does not lead to an own property.
57
+ * - `pin-value-invalid`: the value is not a string that passes
58
+ * `PIN_VALUE_PATTERN`.
59
+ */
60
+ export declare function readPinValue(root: string, file: string, key: string): PinValueResult;
61
+ /** The most hint lines one run returns. */
62
+ export declare const MAX_PIN_HINTS = 8;
63
+ /** The most notes one run returns. */
64
+ export declare const MAX_PIN_NOTES = 8;
65
+ /** The most characters a rendered project root has. */
66
+ export declare const MAX_PIN_ROOT_LENGTH = 256;
67
+ /** Why a pin gave no line, or what the run cut. A fixed vocabulary; a note never echoes data. */
68
+ export type PinNoteCode = PinFailureCode | 'pin-conflict' | 'hints-truncated' | 'notes-truncated';
69
+ /**
70
+ * One reason, with the key of the pinning project when the reason belongs to
71
+ * one. `pin-conflict`, `hints-truncated` and `notes-truncated` carry no
72
+ * identifier and no count.
73
+ */
74
+ export interface PinNote {
75
+ readonly code: PinNoteCode;
76
+ readonly project?: string;
77
+ }
78
+ /** A project the run selected and scanned, as `begin` lists it. */
79
+ export interface PinProject {
80
+ /** The allow-list entry as written. */
81
+ readonly entry: string;
82
+ /** Later allow-list entries that named the same checkout, as written. */
83
+ readonly aliases?: readonly string[];
84
+ /** The resolved main root, as the `projects` block lists it. */
85
+ readonly root: string;
86
+ /** `projectKey(root)`. */
87
+ readonly key: string;
88
+ /** Lowercase `owner/repo` of the GitHub `origin`, when the checkout has one. */
89
+ readonly repo?: string;
90
+ /** The commit HEAD names, when it can be read. */
91
+ readonly commit?: string;
92
+ }
93
+ /** The two reads a pin needs. A seam for tests; the defaults are the real readers. */
94
+ export interface PinReaders {
95
+ readonly readPin: (root: string, file: string, key: string) => PinValueResult;
96
+ readonly readTag: (root: string, head: string) => TagAtHead;
97
+ }
98
+ export interface PinResolution {
99
+ /** Hint lines by the key of the pinning project. */
100
+ readonly hints: Record<string, string[]>;
101
+ /** Sorted, deduplicated and capped. Never a reason to degrade a run. */
102
+ readonly notes: PinNote[];
103
+ }
104
+ /**
105
+ * Turn declared pins into hint lines and notes. Never throws, and opens
106
+ * nothing a selected project does not own.
107
+ *
108
+ * Order: match each pin to a selected project, group by (resolved root,
109
+ * upstream, key), find the selected checkouts of the upstream other than the
110
+ * pinning project, drop a group with none, drop a group whose entries name
111
+ * different files (one `pin-conflict` note, never a pick), and only then read
112
+ * the pin value
113
+ * and each checkout's tag, a checkout's tag once however many pins name it.
114
+ * Groups are resolved in sorted order and resolution stops once the hint cap
115
+ * is passed, so work is bounded by what can be returned. A pin with no
116
+ * selected matching checkout gives nothing, no note either: that case cannot
117
+ * be told from an out-of-selection one without a read.
118
+ */
119
+ export declare function resolvePins(pins: readonly ConnectPin[], projects: readonly PinProject[], overrides?: Partial<PinReaders>): PinResolution;
120
+ /**
121
+ * The well-formed notes of an untrusted value, such as a snapshot read back
122
+ * from disk: a known code, and a project that is a project key. Anything else
123
+ * is dropped, so a stored note cannot carry text into a summary.
124
+ */
125
+ export declare function readPinNotes(value: unknown): PinNote[];
126
+ /**
127
+ * The fixed-form summary line for a run's notes: `Pins: <code>[ (<key>)], ...`,
128
+ * or nothing when there are none. Built from codes and keys only, so it holds
129
+ * no file, key path, value or upstream.
130
+ */
131
+ export declare function renderPinsLine(notes: readonly PinNote[]): string;
@@ -7,24 +7,21 @@
7
7
  * Reads files under `.git/` only, through the contained reader (no symlink is
8
8
  * followed, every read is bounded). No git process and no network is used, and
9
9
  * nothing in a remote URL except the validated `owner/repo` is ever returned,
10
- * so credentials in a URL cannot reach a record. Import rule: node builtins
11
- * and `connect-evidence.ts` only, because the `ce:connect` helper bundles it.
12
- * Never throws: anything unreadable, unexpected or not GitHub is absent.
10
+ * so credentials in a URL cannot reach a record. Import rule: node builtins,
11
+ * `connect-evidence.ts` and `connect-config.ts` only, because the `ce:connect`
12
+ * helper bundles it. Never throws: anything unreadable, unexpected or not GitHub is absent.
13
+ *
14
+ * `readTagAtHead` adds the tag a checkout's HEAD sits on, read from loose refs,
15
+ * `packed-refs` and loose tag objects only, with every walk and inflate bounded.
13
16
  */
17
+ import { isGithubOwnerRepo } from './connect-config.js';
14
18
  export interface RepoIdentity {
15
19
  /** Lowercase `owner/repo` of the GitHub `origin` remote. */
16
20
  readonly repo?: string;
17
21
  /** The full hash HEAD names. */
18
22
  readonly commit?: string;
19
23
  }
20
- /**
21
- * `owner/repo`, shaped as GitHub allows and nothing else. The one rule for a
22
- * repository that is printed into a command, put in an API path or recorded as
23
- * provenance, so every `connect-*` module and the helper agree on it. It checks
24
- * the shape only and keeps the case; it says nothing about whether the
25
- * repository exists.
26
- */
27
- export declare function isGithubOwnerRepo(value: string): boolean;
24
+ export { isGithubOwnerRepo };
28
25
  /**
29
26
  * `owner/repo` of a GitHub remote URL, lowercase, or nothing. Three forms are
30
27
  * read: an https URL, `git@github.com:o/r` and an `ssh://` URL, each with or
@@ -39,3 +36,25 @@ export declare function normalizeGithubRemote(url: string): string | undefined;
39
36
  * symlink) has neither field.
40
37
  */
41
38
  export declare function readRepoIdentity(mainRoot: string): RepoIdentity;
39
+ /**
40
+ * A tag name that may be rendered: it starts alphanumeric, uses a short safe
41
+ * charset and is at most 64 characters. A `/` is allowed because a tag such as
42
+ * `release/1.2` is a real nested ref; nothing here can hold whitespace, a
43
+ * control character or markup.
44
+ */
45
+ export declare const TAG_NAME_PATTERN: RegExp;
46
+ export type TagAtHead = {
47
+ readonly kind: 'tag';
48
+ readonly name: string;
49
+ } | {
50
+ readonly kind: 'unknown';
51
+ };
52
+ /**
53
+ * The one tag whose commit is `head`, for the main checkout at `mainRoot`, or
54
+ * `unknown`. Unknown is the answer for no tag, several tags, a tag object that
55
+ * is not a readable loose object (in a pack, oversize, malformed, nested; a
56
+ * packed tag with no `^` line counts when `packed-refs` is not fully peeled), a
57
+ * walk or inflate past its cap, a symlink, an unsafe name or id and a name
58
+ * that cannot be rendered. Reads `.git` files only and never throws.
59
+ */
60
+ export declare function readTagAtHead(mainRoot: string, head: string): TagAtHead;
@@ -28,9 +28,9 @@ export interface DiscoverSkillsOptions {
28
28
  /** Home directory, injected so tests can use a temp dir instead of the real one. */
29
29
  homeDir: string;
30
30
  /**
31
- * Override for OpenCode's global config directory (mirrors
32
- * `$XDG_CONFIG_HOME` resolution). Defaults to `<homeDir>/.config/opencode`
33
- * when omitted.
31
+ * Override for OpenCode's global config directory. Defaults to
32
+ * `$XDG_CONFIG_HOME/opencode` when that is set, else
33
+ * `<homeDir>/.config/opencode` (the host's own rule), when omitted.
34
34
  */
35
35
  configDir?: string;
36
36
  /**
@@ -0,0 +1,26 @@
1
+ /**
2
+ * The OpenCode user config directory, resolved the way the host resolves it,
3
+ * except for a value the XDG Base Directory spec calls invalid.
4
+ *
5
+ * OpenCode v1 (`packages/core/src/global.ts`, through `xdg-basedir` 5.1.0) and
6
+ * v2 (`packages/util/src/global-roots.ts`) both compute
7
+ * `join(env.XDG_CONFIG_HOME || join(home, '.config'), 'opencode')`. An empty
8
+ * `XDG_CONFIG_HOME` is falsy and falls back to home, here and in the host.
9
+ *
10
+ * The one difference: the spec says these paths must be absolute and that a
11
+ * relative value is invalid and should be ignored, so a non-absolute value
12
+ * counts as unset here. The host would resolve it against the working
13
+ * directory, which would let a checkout ship `<rel>/opencode/systematic.json`
14
+ * and have it read as the trusted user layer (it anchors `connect.allow_projects`
15
+ * and `connect.pins`). The value is otherwise used as given: not trimmed, not
16
+ * normalized.
17
+ *
18
+ * `homeDir` is injected so tests and the loaders can point at a temp home. This
19
+ * is the user-config *default*: an explicit `userConfigDir`, `opencodeConfigDir`
20
+ * or `configDir` still wins at the call site, and `OPENCODE_CONFIG_DIR` is a
21
+ * separate extra directory that this does not read.
22
+ *
23
+ * Import rule: node builtins only. The `ce-connect` and `systematic-search`
24
+ * bundles inline it through `connect-config.ts` and `search-user-config.ts`.
25
+ */
26
+ export declare function opencodeUserConfigDir(homeDir: string, env?: Readonly<Record<string, string | undefined>>): string;
@@ -87,7 +87,7 @@ export interface OpenCodeV2Deps {
87
87
  packageRoot: string;
88
88
  /** Home directory for user-level config and skill discovery. Defaults to `os.homedir()`; tests inject a temp dir. */
89
89
  homeDir?: string;
90
- /** User-level OpenCode config directory. Defaults to `<homeDir>/.config/opencode`. */
90
+ /** User-level OpenCode config directory. Defaults to `$XDG_CONFIG_HOME/opencode` when set, else `<homeDir>/.config/opencode`. */
91
91
  opencodeConfigDir?: string;
92
92
  /** Replaces individual installer slots. Slots left out use the domain's own installer. */
93
93
  installers?: Partial<V2Installers>;
@@ -3,7 +3,7 @@
3
3
  * user-level file selection, and a reader that never touches project config.
4
4
  *
5
5
  * Import rule: this module may import only zod, jsonc-parser, node builtins,
6
- * `search-bounded-read.ts` (node builtins only) and TYPES from `search-core.ts`. It must never import `config.ts` or
6
+ * `opencode-config-dir.ts` and `search-bounded-read.ts` (each node builtins only) and TYPES from `search-core.ts`. It must never import `config.ts` or
7
7
  * `config-schema.ts`; both of those import this module, never the reverse.
8
8
  * The `systematic-search` bin bundles it, and pulling in `config.ts` would
9
9
  * drag the whole config loader (and its jsonc build) into that bundle.
@@ -210,8 +210,10 @@ export interface UserLevelConfigDirs {
210
210
  readonly customConfigDir: string | undefined;
211
211
  }
212
212
  /**
213
- * The user-level config directories: `<home>/.config/opencode`, and the
214
- * `OPENCODE_CONFIG_DIR` directory when it is set. The variable is trimmed and
213
+ * The user-level config directories: `$XDG_CONFIG_HOME/opencode` when that is
214
+ * set, else `<home>/.config/opencode` (OpenCode's own rule, see
215
+ * `opencode-config-dir.ts`), and the `OPENCODE_CONFIG_DIR` directory when it
216
+ * is set. The variable is trimmed and
215
217
  * a blank value counts as unset. `config.ts` and the reader both call this.
216
218
  */
217
219
  export declare function resolveUserLevelConfigDirs(options?: UserLevelConfigDirOptions): UserLevelConfigDirs;