@skitterbyte/skitterspec-linear 18.0.1 → 18.1.1

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.
Files changed (50) hide show
  1. package/MIGRATION.md +81 -0
  2. package/assets/core/env.config.md +36 -9
  3. package/assets/hooks/main-guard.cjs +1 -1
  4. package/assets/hooks/review-gate.cjs +1 -1
  5. package/assets/rules/spec-planning.md +4 -2
  6. package/assets/skills/spec-complete/SKILL.md +67 -25
  7. package/assets/skills/spec-hotfix/SKILL.md +21 -11
  8. package/assets/skills/spec-sync/SKILL.md +10 -1
  9. package/package.json +1 -1
  10. package/src/cli.js +289 -34
  11. package/src/env/config.js +14 -2
  12. package/src/env/hotfix.js +288 -16
  13. package/src/env/hotfixland.js +302 -0
  14. package/src/env/resolve.js +22 -8
  15. package/src/init.js +36 -4
  16. package/src/vendor/linear/api.js +43 -56
  17. package/src/vendor/linear/cli-sanitise.js +2 -2
  18. package/src/vendor/linear/cli-sync.js +87 -390
  19. package/src/vendor/linear/config.js +46 -171
  20. package/src/vendor/linear/credentials.js +40 -370
  21. package/src/vendor/linear/dialect.js +177 -0
  22. package/src/vendor/linear/doctor.js +7 -15
  23. package/src/vendor/linear/identity.js +20 -70
  24. package/src/vendor/linear/released.js +4 -222
  25. package/src/vendor/{sync-core/src → linear}/sanitise.js +4 -3
  26. package/src/vendor/provider-kit/index.js +41 -0
  27. package/src/vendor/provider-kit/src/adapter.js +23 -0
  28. package/src/vendor/provider-kit/src/apply.js +197 -0
  29. package/src/vendor/provider-kit/src/args.js +68 -0
  30. package/src/vendor/provider-kit/src/config.js +198 -0
  31. package/src/vendor/provider-kit/src/credentials.js +404 -0
  32. package/src/vendor/provider-kit/src/doctor.js +35 -0
  33. package/src/vendor/provider-kit/src/http.js +44 -0
  34. package/src/vendor/provider-kit/src/identity.js +93 -0
  35. package/src/vendor/provider-kit/src/md-compare.js +39 -0
  36. package/src/vendor/{sync-core/src/tables.js → provider-kit/src/md-tables.js} +10 -18
  37. package/src/vendor/provider-kit/src/prompt.js +50 -0
  38. package/src/vendor/provider-kit/src/released.js +226 -0
  39. package/src/vendor/provider-kit/src/specs.js +166 -0
  40. package/src/vendor/provider-kit/src/transport.js +22 -0
  41. package/src/vendor/sync-core/index.js +22 -5
  42. package/src/vendor/sync-core/src/compare.js +14 -12
  43. package/src/vendor/sync-core/src/dialect.js +51 -0
  44. package/src/vendor/sync-core/src/fields.js +36 -0
  45. package/src/vendor/sync-core/src/legacy.js +19 -9
  46. package/src/vendor/sync-core/src/normalize.js +30 -158
  47. package/src/vendor/sync-core/src/push.js +1 -1
  48. package/src/vendor/sync-core/src/retarget.js +21 -17
  49. package/src/vendor/sync-core/src/verify.js +24 -45
  50. package/src/vendor/sync-core/src/write.js +7 -5
@@ -0,0 +1,68 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * A table-driven flag parser for a provider CLI, carrying the one discipline
5
+ * the first provider learned the hard way: an UNKNOWN `--flag` is a refusal,
6
+ * never a silent positional. (A renamed flag once parsed as a no-op — the
7
+ * repair invocation ran the wrong command, ignored the flag, and exited 0.)
8
+ *
9
+ * The table maps `--flag` → spec:
10
+ * - `{ kind: 'boolean' }` sets `flags[name] = true`
11
+ * - `{ kind: 'value' }` takes the next token verbatim
12
+ * - `{ kind: 'string' }` takes the next token, trimmed ('' kept)
13
+ * - `{ kind: 'number' }` Number(next token)
14
+ * - `{ kind: 'path' }` path.resolve(next token)
15
+ * - `{ kind: 'list' }` repeatable; pushes trimmed tokens
16
+ * - `{ kind: 'custom', take, handle }` `handle(flags, value, context)`;
17
+ * `take: false` consumes no token
18
+ * - any spec may set `name` (defaults to the camelCased flag)
19
+ *
20
+ * A spec name never starts with `--`, so the refusal cannot swallow a real
21
+ * argument. `renamed` maps an old flag to advice lines appended to the refusal,
22
+ * so a rename hands off instead of leaving the caller to guess.
23
+ */
24
+
25
+ const path = require('node:path')
26
+
27
+ const camel = (flag) => flag.replace(/^--/, '').replace(/-([a-z])/g, (_, c) => c.toUpperCase())
28
+
29
+ function parseFlags(args, table, { defaults = {}, renamed = {}, context = {} } = {}) {
30
+ const flags = { ...defaults }
31
+ const positional = []
32
+ const unknown = []
33
+ for (let i = 0; i < args.length; i++) {
34
+ const token = args[i]
35
+ const spec = table[token]
36
+ if (!spec) {
37
+ if (String(token).startsWith('--')) unknown.push(token)
38
+ else positional.push(token)
39
+ continue
40
+ }
41
+ const name = spec.name || camel(token)
42
+ const kind = spec.kind || 'boolean'
43
+ if (kind === 'boolean') flags[name] = true
44
+ else if (kind === 'value') flags[name] = args[++i]
45
+ else if (kind === 'string') flags[name] = String(args[++i] || '').trim()
46
+ else if (kind === 'number') flags[name] = Number(args[++i])
47
+ else if (kind === 'path') flags[name] = path.resolve(args[++i])
48
+ else if (kind === 'list') (flags[name] = flags[name] || []).push(String(args[++i] || '').trim())
49
+ else if (kind === 'custom') {
50
+ const value = spec.take === false ? undefined : args[++i]
51
+ spec.handle(flags, value, context)
52
+ } else throw new Error(`parseFlags: unknown kind "${kind}" for ${token}`)
53
+ }
54
+ return { flags, positional, unknown }
55
+ }
56
+
57
+ // The refusal, phrased once. Returns the lines to print (the caller owns the
58
+ // stream and the exit code).
59
+ function unknownFlagLines(program, unknown, renamed = {}) {
60
+ const lines = [`${program}: unknown flag ${unknown.join(', ')}`]
61
+ for (const flag of unknown) {
62
+ if (renamed[flag]) for (const advice of [].concat(renamed[flag])) lines.push(` ${advice}`)
63
+ }
64
+ lines.push(` run \`${program}\` for the full usage.`)
65
+ return lines
66
+ }
67
+
68
+ module.exports = { parseFlags, unknownFlagLines }
@@ -0,0 +1,198 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * Config-merge machinery shared by every provider's loader.
5
+ *
6
+ * A provider's config is a committed JSON file merged over its own defaults —
7
+ * only known keys copied (unknown ignored for forward-compat), typed fields
8
+ * validated LOUDLY where a typo would otherwise read as a deliberate choice.
9
+ * The defaults, the file name and the vocabularies are the provider's; the
10
+ * merge and validation shapes are identical across providers, so they live
11
+ * here, bound to the provider by `makeMergeHelpers`.
12
+ *
13
+ * Every thrown message names the provider's own config file, so a refusal
14
+ * points at the file the user actually edits.
15
+ */
16
+
17
+ function isObject(value) {
18
+ return value != null && typeof value === 'object' && !Array.isArray(value)
19
+ }
20
+
21
+ // Normalise an array config value to trimmed, non-empty strings.
22
+ function stringList(value) {
23
+ return value.filter((s) => typeof s === 'string' && s.trim()).map((s) => s.trim())
24
+ }
25
+
26
+ // Copy a typed field from parsed[key] onto base[key] when it matches `type`.
27
+ // Strings are trimmed and must be non-empty to override; `string?` may be empty.
28
+ function assign(base, parsed, key, type) {
29
+ const v = parsed[key]
30
+ if (type === 'string') {
31
+ if (typeof v === 'string' && v.trim()) base[key] = v.trim()
32
+ } else if (type === 'string?') {
33
+ if (typeof v === 'string') base[key] = v
34
+ } else if (type === 'boolean') {
35
+ if (typeof v === 'boolean') base[key] = v
36
+ }
37
+ }
38
+
39
+ /**
40
+ * The provider-bound validators. `configFile` is only used in messages;
41
+ * `ownership` / `lifecycleBuckets` / `phaseMappings` are the provider's own
42
+ * vocabularies (they rarely differ between providers, but they are the
43
+ * provider's to declare).
44
+ */
45
+ function makeMergeHelpers({ configFile, ownership, lifecycleBuckets, phaseMappings }) {
46
+ // Merge (and validate) sync.fieldOwnership. Any key the caller lists joins
47
+ // the compared field set; the value MUST be one of the ownership modes.
48
+ function mergeFieldOwnership(base, parsed) {
49
+ if (!isObject(parsed)) return
50
+ for (const [field, dir] of Object.entries(parsed)) {
51
+ if (!ownership.includes(dir)) {
52
+ throw new Error(
53
+ `Invalid ${configFile}: sync.fieldOwnership.${field} = ${JSON.stringify(dir)} ` +
54
+ `(expected one of ${ownership.join('|')})`,
55
+ )
56
+ }
57
+ base[field] = dir
58
+ }
59
+ }
60
+
61
+ // Merge (and validate) `mapping.phases` in either of its two forms: a scalar
62
+ // mode for the whole repo, or a map of lifecycle bucket → mode. Loud on a bad
63
+ // key or value — a misspelt bucket would otherwise read as a deliberate
64
+ // default and go on minting the sub-issues the config was written to stop.
65
+ function mergePhaseMapping(base, parsed) {
66
+ const value = parsed.phases
67
+ if (typeof value === 'string') {
68
+ if (value.trim()) base.phases = value.trim()
69
+ } else if (isObject(value)) {
70
+ const byBucket = {}
71
+ for (const [bucket, mode] of Object.entries(value)) {
72
+ if (!lifecycleBuckets.includes(bucket)) {
73
+ throw new Error(
74
+ `Invalid ${configFile}: mapping.phases.${bucket} is not a lifecycle bucket ` +
75
+ `(expected one of ${lifecycleBuckets.join('|')})`,
76
+ )
77
+ }
78
+ if (!phaseMappings.includes(mode)) {
79
+ throw new Error(
80
+ `Invalid ${configFile}: mapping.phases.${bucket} = ${JSON.stringify(mode)} ` +
81
+ `(expected one of ${phaseMappings.join('|')})`,
82
+ )
83
+ }
84
+ byBucket[bucket] = mode
85
+ }
86
+ base.phases = byBucket
87
+ } else if (value !== undefined) {
88
+ throw new Error(
89
+ `Invalid ${configFile}: mapping.phases = ${JSON.stringify(value)} ` +
90
+ `(expected one of ${phaseMappings.join('|')}, or a map of lifecycle bucket to mode)`,
91
+ )
92
+ }
93
+ if (typeof base.phases === 'string' && !phaseMappings.includes(base.phases)) {
94
+ throw new Error(
95
+ `Invalid ${configFile}: mapping.phases = ${JSON.stringify(base.phases)} ` +
96
+ `(expected one of ${phaseMappings.join('|')}, or a map of lifecycle bucket to mode)`,
97
+ )
98
+ }
99
+ }
100
+
101
+ // Merge (and validate) `release.stages` — the project's deployment ladder.
102
+ //
103
+ // Loud on a malformed entry: this list names tracker states, and a tracker
104
+ // that silently ignores an unknown state would let a half-typed ladder push
105
+ // clean and move nothing — so a bad shape fails here, at load, rather than at
106
+ // the first deploy nobody is watching. An ABSENT `release` block is not an
107
+ // error: it is the opt-out, and the whole feature is unused without it.
108
+ function mergeReleaseStages(base, parsed) {
109
+ const value = parsed.stages
110
+ if (value === undefined) return
111
+ if (!Array.isArray(value)) {
112
+ throw new Error(
113
+ `Invalid ${configFile}: release.stages = ${JSON.stringify(value)} ` +
114
+ '(expected an array of { key, state })',
115
+ )
116
+ }
117
+ const stages = []
118
+ const seen = new Set()
119
+ value.forEach((entry, i) => {
120
+ if (!isObject(entry)) {
121
+ throw new Error(
122
+ `Invalid ${configFile}: release.stages[${i}] = ${JSON.stringify(entry)} ` +
123
+ '(expected { key, state })',
124
+ )
125
+ }
126
+ for (const field of ['key', 'state']) {
127
+ if (typeof entry[field] !== 'string' || !entry[field].trim()) {
128
+ throw new Error(
129
+ `Invalid ${configFile}: release.stages[${i}].${field} = ${JSON.stringify(entry[field])} ` +
130
+ '(expected a non-empty string)',
131
+ )
132
+ }
133
+ }
134
+ const key = entry.key.trim()
135
+ if (seen.has(key)) {
136
+ throw new Error(
137
+ `Invalid ${configFile}: release.stages[${i}].key = ${JSON.stringify(key)} is a duplicate ` +
138
+ '(a stage key is how CI names the rung, so it must be unique)',
139
+ )
140
+ }
141
+ seen.add(key)
142
+ stages.push({ key, state: entry.state.trim() })
143
+ })
144
+ base.stages = stages
145
+ }
146
+
147
+ // Merge (and validate) release.ignorePaths — the path prefixes whose commits
148
+ // are bookkeeping. Loud on anything but an array of non-empty strings: a bad
149
+ // value that quietly fell back would let a project believe it had opted out
150
+ // and go on double-counting tickets. A BLANK entry is rejected rather than
151
+ // dropped — `""` is a prefix of every path, so a stray empty string would
152
+ // silently ignore every commit in the range and report a release as
153
+ // containing nothing: the loudest possible wrong answer, arriving as silence.
154
+ function mergeReleaseIgnorePaths(base, parsed) {
155
+ const value = parsed.ignorePaths
156
+ if (value === undefined) return
157
+ if (!Array.isArray(value)) {
158
+ throw new Error(
159
+ `Invalid ${configFile}: release.ignorePaths = ${JSON.stringify(value)} ` +
160
+ '(expected an array of repo-relative path prefixes)',
161
+ )
162
+ }
163
+ value.forEach((entry, i) => {
164
+ if (typeof entry !== 'string' || !entry.trim()) {
165
+ throw new Error(
166
+ `Invalid ${configFile}: release.ignorePaths[${i}] = ${JSON.stringify(entry)} ` +
167
+ '(expected a non-empty repo-relative path prefix, e.g. "specs/")',
168
+ )
169
+ }
170
+ })
171
+ base.ignorePaths = stringList(value)
172
+ }
173
+
174
+ // Merge (and validate) sync.keyedFields. Each value is the item's id property
175
+ // name (a non-empty string); a field listed here is compared per item.
176
+ function mergeKeyedFields(base, parsed) {
177
+ if (!isObject(parsed)) return
178
+ for (const [field, idKey] of Object.entries(parsed)) {
179
+ if (typeof idKey !== 'string' || !idKey.trim()) {
180
+ throw new Error(
181
+ `Invalid ${configFile}: sync.keyedFields.${field} = ${JSON.stringify(idKey)} ` +
182
+ '(expected the item id property name, a non-empty string)',
183
+ )
184
+ }
185
+ base[field] = idKey.trim()
186
+ }
187
+ }
188
+
189
+ return {
190
+ mergeFieldOwnership,
191
+ mergePhaseMapping,
192
+ mergeReleaseStages,
193
+ mergeReleaseIgnorePaths,
194
+ mergeKeyedFields,
195
+ }
196
+ }
197
+
198
+ module.exports = { isObject, stringList, assign, makeMergeHelpers }
@@ -0,0 +1,404 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * The user-level credentials store, shared by every skitterspec provider —
5
+ * where an API credential lives when it is not in the environment.
6
+ *
7
+ * A repo's committed provider config deliberately holds only the NAME of an
8
+ * env var, never a credential. This store is the alternative: one file per
9
+ * machine, outside every repo, at
10
+ * `$XDG_CONFIG_HOME/skitterspec/credentials.json` (else `~/.config/…`).
11
+ *
12
+ * TWO SCHEMAS, one file. v1 — `{ version: 1, teams: { <scopeId>: entry } }` —
13
+ * predates providers being plural, so every v1 entry belongs to the one
14
+ * provider that existed then (the factory names it as `legacyV1Owner`). v2
15
+ * namespaces: `{ version: 2, providers: { <name>: { teams: {…} } } }`. Reads
16
+ * understand both. Writes by the legacy owner keep a v1 store v1 — older CLIs
17
+ * still read it, and its tests pin the shape — while the FIRST write by any
18
+ * other provider migrates the file to v2, folding the v1 entries under the
19
+ * legacy owner. That is the moment two providers actually share the file, and
20
+ * before it nothing changes shape underneath anyone.
21
+ *
22
+ * An entry's `key` may be a string (a bare API key) or an object (a compound
23
+ * credential such as email + token) — the store passes it through opaquely.
24
+ *
25
+ * Reads never throw: every failure returns a structured reason, and a missing
26
+ * store is the normal default, not a problem. Nothing here ever returns a key
27
+ * inside an error, and callers must keep it out of logs, plans, snapshots and
28
+ * stamped frontmatter.
29
+ */
30
+
31
+ const { spawnSync } = require('node:child_process')
32
+ const fs = require('node:fs')
33
+ const os = require('node:os')
34
+ const path = require('node:path')
35
+
36
+ const DIR_NAME = 'skitterspec'
37
+ const FILE_NAME = 'credentials.json'
38
+
39
+ // Modes wider than owner-only. Checked ssh-style: a store other users can read
40
+ // is refused rather than read, because silently using it would hide the leak,
41
+ // and silently chmod'ing someone's file is not ours to do.
42
+ const GROUP_OR_WORLD = 0o077
43
+
44
+ // 60s: a password manager may prompt for biometric or a master password, and a
45
+ // hang here would look like the CLI itself wedging.
46
+ const COMMAND_TIMEOUT_MS = 60_000
47
+
48
+ /**
49
+ * Absolute path of the store. Honours `$XDG_CONFIG_HOME`, else `~/.config`.
50
+ * `env` and `homedir` are injected so tests never touch a real home directory.
51
+ */
52
+ function storePath(env = process.env, homedir = os.homedir) {
53
+ const xdg = env.XDG_CONFIG_HOME && env.XDG_CONFIG_HOME.trim()
54
+ const base = xdg || path.join(homedir(), '.config')
55
+ return path.join(base, DIR_NAME, FILE_NAME)
56
+ }
57
+
58
+ /**
59
+ * Read the store (schema-agnostic).
60
+ *
61
+ * @returns {object} `{ ok: true, store, path }` — parsed and owner-only;
62
+ * `{ ok: false, reason, code, path }` otherwise. `code` is one of:
63
+ * `absent` (no file — the normal default, not a problem), `permissions`
64
+ * (group/world readable), `unreadable`, `malformed`.
65
+ */
66
+ function readStore(file, { stat = fs.statSync, read = fs.readFileSync } = {}) {
67
+ let info
68
+ try {
69
+ info = stat(file)
70
+ } catch (err) {
71
+ if (err.code === 'ENOENT') {
72
+ return { ok: false, code: 'absent', path: file, reason: `no credentials store at ${file}` }
73
+ }
74
+ return { ok: false, code: 'unreadable', path: file, reason: `cannot read ${file}: ${err.message}` }
75
+ }
76
+
77
+ if (info.mode & GROUP_OR_WORLD) {
78
+ const mode = (info.mode & 0o777).toString(8)
79
+ return {
80
+ ok: false,
81
+ code: 'permissions',
82
+ path: file,
83
+ reason:
84
+ `credentials store ${file} is mode ${mode} — readable by other users.\n` +
85
+ ` Run: chmod 600 ${file}`,
86
+ }
87
+ }
88
+
89
+ let raw
90
+ try {
91
+ raw = read(file, 'utf-8')
92
+ } catch (err) {
93
+ return { ok: false, code: 'unreadable', path: file, reason: `cannot read ${file}: ${err.message}` }
94
+ }
95
+
96
+ let store
97
+ try {
98
+ store = JSON.parse(raw)
99
+ } catch (err) {
100
+ return { ok: false, code: 'malformed', path: file, reason: `invalid JSON in ${file}: ${err.message}` }
101
+ }
102
+ if (!store || typeof store !== 'object' || Array.isArray(store)) {
103
+ return { ok: false, code: 'malformed', path: file, reason: `invalid credentials store in ${file}` }
104
+ }
105
+ return { ok: true, store, path: file }
106
+ }
107
+
108
+ /** The store's permission bits as an octal string, or null when absent. */
109
+ function storeMode(file, deps = {}) {
110
+ const stat = deps.stat || fs.statSync
111
+ try {
112
+ return (stat(file).mode & 0o777).toString(8)
113
+ } catch {
114
+ return null
115
+ }
116
+ }
117
+
118
+ // Last 4 characters, for reporting that a key exists without revealing it.
119
+ // Compound (object) credentials have no meaningful tail — null, never a dump.
120
+ function fingerprint(key) {
121
+ if (typeof key !== 'string' || !key) return null
122
+ return `…${key.slice(-4)}`
123
+ }
124
+
125
+ // The provider's scope map (`teams`) inside a parsed store, resolving both
126
+ // schemas. Returns `null` when the store holds nothing for this provider —
127
+ // which for a v1 store is every provider except the legacy owner.
128
+ function scopeMapOf(store, provider, legacyV1Owner) {
129
+ if (!store || typeof store !== 'object') return null
130
+ if (store.providers && typeof store.providers === 'object') {
131
+ const entry = store.providers[provider]
132
+ return entry && typeof entry.teams === 'object' ? entry.teams : null
133
+ }
134
+ if (provider !== legacyV1Owner) return null
135
+ return store.teams && typeof store.teams === 'object' ? store.teams : null
136
+ }
137
+
138
+ function defaultRunCommand(command, timeout) {
139
+ const r = spawnSync('sh', ['-c', command], { encoding: 'utf-8', timeout })
140
+ if (r.error) return { ok: false, error: r.error.message }
141
+ if (r.status !== 0) {
142
+ // stderr only — stdout is the secret, and must not reach an error message.
143
+ const detail = (r.stderr || '').trim().split('\n')[0] || `exit ${r.status}`
144
+ return { ok: false, error: detail }
145
+ }
146
+ return { ok: true, stdout: r.stdout }
147
+ }
148
+
149
+ /**
150
+ * A store bound to one provider. `legacyV1Owner` names the provider whose
151
+ * entries a v1 store holds — the one that predates the namespace; a provider
152
+ * IS that owner exactly when the names match.
153
+ */
154
+ function makeCredentialsStore({ provider, legacyV1Owner }) {
155
+ if (!provider) throw new Error('makeCredentialsStore: provider name required')
156
+ const ownsV1 = provider === legacyV1Owner
157
+
158
+ const mapOf = (store) => scopeMapOf(store, provider, legacyV1Owner)
159
+
160
+ function entryFor(store, scopeId) {
161
+ if (!scopeId) return null
162
+ const map = mapOf(store)
163
+ const entry = map ? map[scopeId] : null
164
+ return entry && typeof entry === 'object' ? entry : null
165
+ }
166
+
167
+ function keyFor(store, scopeId) {
168
+ const entry = entryFor(store, scopeId)
169
+ if (!entry) return null
170
+ const key = entry.key
171
+ if (typeof key === 'string') return key.trim() || null
172
+ return null
173
+ }
174
+
175
+ // A compound (object) credential, for providers whose auth is more than one
176
+ // string. Strings resolve through `keyFor`; this never trims or reshapes.
177
+ function credentialFor(store, scopeId) {
178
+ const entry = entryFor(store, scopeId)
179
+ if (!entry) return null
180
+ return entry.key && typeof entry.key === 'object' ? entry.key : null
181
+ }
182
+
183
+ function userFor(store, scopeId) {
184
+ const entry = entryFor(store, scopeId)
185
+ if (!entry) return null
186
+ const user = entry.user
187
+ if (!user || typeof user !== 'object') return null
188
+ // The id is what an assignment is actually made with, so an entry without
189
+ // one is not a partial identity — it is no identity at all.
190
+ const id = typeof user.id === 'string' && user.id.trim() ? user.id.trim() : null
191
+ if (!id) return null
192
+ const name = typeof user.name === 'string' && user.name.trim() ? user.name.trim() : null
193
+ return { id, name }
194
+ }
195
+
196
+ /**
197
+ * Resolve one scope's key from the store: a stored `key` first, else running
198
+ * its `keyCommand` and taking stdout.
199
+ *
200
+ * `keyCommand` is honoured ONLY from this user-level store — never from a
201
+ * repo's committed config, which travels with the repo and would let a cloned
202
+ * repo run arbitrary code. A command that fails, times out or prints nothing
203
+ * resolves to no key — the ordinary "fall back" state — but its stderr is
204
+ * carried back so a broken command is diagnosable. Its **stdout is never**
205
+ * put in an error: that is the key.
206
+ */
207
+ function resolveKey(store, scopeId, deps = {}) {
208
+ const direct = keyFor(store, scopeId)
209
+ if (direct) return { key: direct, source: 'store' }
210
+
211
+ const entry = entryFor(store, scopeId)
212
+ const command = entry && typeof entry.keyCommand === 'string' ? entry.keyCommand.trim() : ''
213
+ if (!command) return { key: null, source: null }
214
+
215
+ const run = deps.run || defaultRunCommand
216
+ const result = run(command, deps.timeoutMs || COMMAND_TIMEOUT_MS)
217
+ if (!result.ok) {
218
+ return { key: null, source: null, command, reason: `keyCommand failed: ${result.error}` }
219
+ }
220
+ const key = (result.stdout || '').trim()
221
+ if (!key) {
222
+ return { key: null, source: null, command, reason: 'keyCommand produced no output' }
223
+ }
224
+ return { key, source: 'command', command }
225
+ }
226
+
227
+ // Read-modify-write of this provider's scope map, with the schema rules from
228
+ // the module header. `mutate(entry)` returns the scope's next entry, or the
229
+ // literal string 'delete' to drop it; `mutate` receives the current entry (or
230
+ // null). Refuses on an unreadable or over-permissive store, exactly like a
231
+ // read — silently rewriting a world-readable file would leave the leak.
232
+ function mutateEntry(file, scopeId, mutate, deps = {}) {
233
+ const mkdir = deps.mkdir || fs.mkdirSync
234
+ const write = deps.write || fs.writeFileSync
235
+ const chmod = deps.chmod || fs.chmodSync
236
+ const exists = deps.exists || fs.existsSync
237
+
238
+ const created = !exists(file)
239
+ let store = null
240
+ if (!created) {
241
+ const current = readStore(file, deps)
242
+ if (!current.ok) return { ok: false, reason: current.reason, code: current.code }
243
+ store = current.store
244
+ }
245
+
246
+ // Decide the shape this write leaves behind.
247
+ const isV2 = !!(store && store.providers && typeof store.providers === 'object')
248
+ if (!store) {
249
+ store = ownsV1 ? { version: 1, teams: {} } : { version: 2, providers: {} }
250
+ } else if (!isV2 && !ownsV1) {
251
+ // The first write by a second provider: fold the v1 entries under their
252
+ // owner and namespace the file. This is the one moment the shape changes.
253
+ const legacyTeams = store.teams && typeof store.teams === 'object' ? store.teams : {}
254
+ store = { version: 2, providers: { [legacyV1Owner]: { teams: legacyTeams } } }
255
+ }
256
+
257
+ let map
258
+ if (store.providers && typeof store.providers === 'object') {
259
+ if (!store.providers[provider] || typeof store.providers[provider] !== 'object') {
260
+ store.providers[provider] = { teams: {} }
261
+ }
262
+ if (!store.providers[provider].teams || typeof store.providers[provider].teams !== 'object') {
263
+ store.providers[provider].teams = {}
264
+ }
265
+ if (!store.version || store.version < 2) store.version = 2
266
+ map = store.providers[provider].teams
267
+ } else {
268
+ if (!store.teams || typeof store.teams !== 'object') store.teams = {}
269
+ if (!store.version) store.version = 1
270
+ map = store.teams
271
+ }
272
+
273
+ const current = map[scopeId] && typeof map[scopeId] === 'object' ? map[scopeId] : null
274
+ const next = mutate(current)
275
+ if (next === 'delete') {
276
+ if (!current) return { ok: true, path: file, created: false, removed: false }
277
+ delete map[scopeId]
278
+ } else if (next !== undefined) {
279
+ map[scopeId] = next
280
+ }
281
+
282
+ mkdir(path.dirname(file), { recursive: true, mode: 0o700 })
283
+ write(file, JSON.stringify(store, null, 2) + '\n', { mode: 0o600 })
284
+ // `mode` on writeFileSync only applies when the file is CREATED, so an
285
+ // existing file keeps its mode — narrow it explicitly.
286
+ chmod(file, 0o600)
287
+ return { ok: true, path: file, created, removed: next === 'delete' }
288
+ }
289
+
290
+ /** Record a credential (string key or compound object) for one scope. */
291
+ function writeKey(file, scopeId, key, deps = {}) {
292
+ if (!scopeId) return { ok: false, reason: 'no team id — nothing to key the entry by' }
293
+ const isCompound = key && typeof key === 'object'
294
+ const value = isCompound ? key : typeof key === 'string' ? key.trim() : ''
295
+ if (!value || (isCompound && !Object.keys(value).length)) {
296
+ return { ok: false, reason: 'empty key — nothing stored' }
297
+ }
298
+ return mutateEntry(file, scopeId, (entry) => ({ ...(entry || {}), key: value }), deps)
299
+ }
300
+
301
+ /** Record the identity for one scope, preserving its credential. */
302
+ function writeUser(file, scopeId, user, deps = {}) {
303
+ if (!scopeId) return { ok: false, reason: 'no team id — nothing to key the entry by' }
304
+ const id = user && typeof user.id === 'string' ? user.id.trim() : ''
305
+ if (!id) return { ok: false, reason: 'no user id — nothing stored' }
306
+ const name = user && typeof user.name === 'string' ? user.name.trim() : ''
307
+ return mutateEntry(
308
+ file,
309
+ scopeId,
310
+ (entry) => ({ ...(entry || {}), user: name ? { id, name } : { id } }),
311
+ deps,
312
+ )
313
+ }
314
+
315
+ /**
316
+ * Record a command for one scope instead of a key. Unlike a key, a command is
317
+ * not a secret, so this one IS safe to pass as an argument. `literalKeyRe`
318
+ * (with `literalKeyAdvice`) is the provider's own key shape — a command with
319
+ * a key written into it is refused at the door, because a command is
320
+ * displayed by `credentials status` and never treated as a secret.
321
+ */
322
+ function writeKeyCommand(file, scopeId, command, deps = {}, { literalKeyRe, literalKeyAdvice } = {}) {
323
+ if (!scopeId) return { ok: false, reason: 'no team id — nothing to key the entry by' }
324
+ if (typeof command !== 'string' || !command.trim()) {
325
+ return { ok: false, reason: 'empty command — nothing stored' }
326
+ }
327
+ if (literalKeyRe && literalKeyRe.test(command)) {
328
+ return { ok: false, reason: literalKeyAdvice || 'that command has a key written into it.' }
329
+ }
330
+ // A command REPLACES a stored key for that scope — keeping both would mean
331
+ // the key silently wins and the command never runs.
332
+ return mutateEntry(file, scopeId, () => ({ keyCommand: command.trim() }), deps)
333
+ }
334
+
335
+ /** Remove one scope's entry entirely. Absent store or entry is a clean no-op. */
336
+ function removeKey(file, scopeId, deps = {}) {
337
+ const current = readStore(file, deps)
338
+ if (!current.ok) {
339
+ if (current.code === 'absent') return { ok: true, path: file, removed: false }
340
+ return { ok: false, reason: current.reason, code: current.code }
341
+ }
342
+ if (!entryFor(current.store, scopeId)) return { ok: true, path: file, removed: false }
343
+ const r = mutateEntry(file, scopeId, () => 'delete', deps)
344
+ return r.ok ? { ok: true, path: file, removed: true } : r
345
+ }
346
+
347
+ /**
348
+ * Forget the identity recorded for one scope, leaving its KEY in place.
349
+ * Deliberately not `removeKey`'s shape: that one drops the whole entry, which
350
+ * is right when the key is being revoked; here it would sign the user out
351
+ * entirely because they corrected their own name.
352
+ */
353
+ function removeUser(file, scopeId, deps = {}) {
354
+ const current = readStore(file, deps)
355
+ if (!current.ok) {
356
+ if (current.code === 'absent') return { ok: true, path: file, removed: false }
357
+ return { ok: false, reason: current.reason, code: current.code }
358
+ }
359
+ const entry = entryFor(current.store, scopeId)
360
+ if (!entry || !entry.user) return { ok: true, path: file, removed: false }
361
+ const r = mutateEntry(
362
+ file,
363
+ scopeId,
364
+ (e) => {
365
+ const next = { ...(e || {}) }
366
+ delete next.user
367
+ return next
368
+ },
369
+ deps,
370
+ )
371
+ return r.ok ? { ok: true, path: file, removed: true } : r
372
+ }
373
+
374
+ return {
375
+ provider,
376
+ storePath,
377
+ readStore,
378
+ storeMode,
379
+ fingerprint,
380
+ entryFor,
381
+ keyFor,
382
+ credentialFor,
383
+ userFor,
384
+ resolveKey,
385
+ writeKey,
386
+ writeUser,
387
+ writeKeyCommand,
388
+ removeKey,
389
+ removeUser,
390
+ }
391
+ }
392
+
393
+ module.exports = {
394
+ makeCredentialsStore,
395
+ storePath,
396
+ readStore,
397
+ storeMode,
398
+ fingerprint,
399
+ defaultRunCommand,
400
+ COMMAND_TIMEOUT_MS,
401
+ DIR_NAME,
402
+ FILE_NAME,
403
+ GROUP_OR_WORLD,
404
+ }