peaks-loop 4.2.0 → 4.2.2
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/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +165 -0
- package/contracts/readonly-argv-whitelist.json +116 -0
- package/dist/cli/commands/code-auto-compact-command.js +15 -3
- package/dist/cli/commands/core/skill-presence-housekeeping-commands.js +7 -1
- package/dist/cli/commands/mut-commands-helpers.js +42 -36
- package/dist/cli/commands/project-context-command.js +7 -2
- package/dist/cli/commands/workspace/init-actions.js +5 -0
- package/dist/cli/commands/workspace/init-context.js +1 -0
- package/dist/services/code/auto-compact-artifacts.js +42 -10
- package/dist/services/code/auto-compact-checkpoint-content.d.ts +49 -0
- package/dist/services/code/auto-compact-checkpoint-content.js +157 -0
- package/dist/services/code/auto-compact-envelopes.d.ts +11 -2
- package/dist/services/code/auto-compact-envelopes.js +18 -4
- package/dist/services/code/auto-compact-orchestrator.js +1 -1
- package/dist/services/hooks/auto-compact-hook-install.d.ts +13 -3
- package/dist/services/hooks/auto-compact-hook-install.js +13 -3
- package/dist/services/mcp/context-tool.d.ts +3 -0
- package/dist/services/mcp/context-tool.js +135 -0
- package/dist/services/mcp/surface.js +7 -1
- package/dist/services/mcp/tools.js +3 -1
- package/dist/services/memory/project-context-service.d.ts +10 -1
- package/dist/services/memory/project-context-service.js +13 -6
- package/dist/services/prd/project-scan-body-tables.d.ts +33 -0
- package/dist/services/prd/project-scan-body-tables.js +185 -0
- package/dist/services/prd/project-scan-bootstrap-service.d.ts +16 -3
- package/dist/services/prd/project-scan-bootstrap-service.js +127 -231
- package/dist/services/prd/project-scan-content.d.ts +24 -0
- package/dist/services/prd/project-scan-content.js +207 -0
- package/dist/services/prd/project-scan-existing-state.d.ts +22 -0
- package/dist/services/prd/project-scan-existing-state.js +61 -0
- package/dist/services/prd/project-scan-field-refresh.d.ts +87 -0
- package/dist/services/prd/project-scan-field-refresh.js +217 -0
- package/dist/services/prd/project-scan-frontmatter.d.ts +32 -0
- package/dist/services/prd/project-scan-frontmatter.js +34 -0
- package/dist/services/prd/project-scan-library-versions.d.ts +60 -0
- package/dist/services/prd/project-scan-library-versions.js +135 -0
- package/dist/services/prd/project-scan-techstack.d.ts +34 -0
- package/dist/services/prd/project-scan-techstack.js +167 -0
- package/package.json +6 -6
- package/skills/peaks-code/SKILL.md +1 -1
- package/skills/peaks-code/references/project-scan-checklist.md +3 -1
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reading the frontmatter block out of a `.peaks/project-scan/project-scan.md`.
|
|
3
|
+
*
|
|
4
|
+
* Split out of `project-scan-field-refresh.ts` to stay under the `src/**`
|
|
5
|
+
* 300-line cap, and because the CRLF problem is its own subject: every caller
|
|
6
|
+
* that wants the frontmatter needs the same two facts (the block, and where the
|
|
7
|
+
* body begins), and getting them wrong on a Windows checkout is what re-freezes
|
|
8
|
+
* the scan.
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* Split the leading `---` block.
|
|
12
|
+
*
|
|
13
|
+
* CRLF-TOLERANT ON PURPOSE. `core.autocrlf=true` is the default on Windows, so a
|
|
14
|
+
* checkout can hand this module a file whose fences are `---\r\n`. A pattern
|
|
15
|
+
* anchored on `\n` alone finds no frontmatter there and the refresh refuses —
|
|
16
|
+
* reviving the exact freeze the refresh exists to end, on the platform most of
|
|
17
|
+
* its users run. The block is returned with `\n` endings so the yaml AST offsets
|
|
18
|
+
* and the span arithmetic agree; `crlf` records what the file actually uses, so
|
|
19
|
+
* the writer can put it back.
|
|
20
|
+
*/
|
|
21
|
+
export function splitFrontmatter(content) {
|
|
22
|
+
const match = /^---(\r?\n)([\s\S]*?)\r?\n---/.exec(content);
|
|
23
|
+
if (match === null)
|
|
24
|
+
return null;
|
|
25
|
+
return {
|
|
26
|
+
frontmatter: (match[2] ?? '').replace(/\r\n/g, '\n'),
|
|
27
|
+
bodyStart: match[0].length,
|
|
28
|
+
crlf: match[1] === '\r\n'
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
/** The frontmatter block alone, or `null`. */
|
|
32
|
+
export function frontmatterOf(content) {
|
|
33
|
+
return splitFrontmatter(content)?.frontmatter ?? null;
|
|
34
|
+
}
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `libraryVersions` map a project scan records, derived from `scanLibraries`.
|
|
3
|
+
*
|
|
4
|
+
* WHY THE ROOT MANIFEST DECIDES. In a monorepo the scan concatenates every
|
|
5
|
+
* workspace `package.json`, so one name appears once per declaring package with
|
|
6
|
+
* that package's own spec — `typescript` arrives as BOTH the root's `^5.7.2` and
|
|
7
|
+
* a workspace package's `^5.4.0`, and a package used only by a workspace
|
|
8
|
+
* (`ecc-universal`) appears with no root declaration at all. Taking the first row
|
|
9
|
+
* records whichever specifier sorts first, which is the workspace's, not the
|
|
10
|
+
* project's. peaks-rd cross-checks this map against the breaking-changes table,
|
|
11
|
+
* and a floor is exactly the wrong version to file a project under.
|
|
12
|
+
*
|
|
13
|
+
* Split out of `project-scan-field-refresh.ts` to stay under the `src/**`
|
|
14
|
+
* 300-line cap.
|
|
15
|
+
*/
|
|
16
|
+
/**
|
|
17
|
+
* The root manifest's own dependency map: name → specifier, across every scope.
|
|
18
|
+
*
|
|
19
|
+
* THE ROOT MANIFEST IS THE SOURCE OF THE SPECIFIER, not the scan's row order.
|
|
20
|
+
* This used to be built by taking the first row `scanLibraries` emitted for each
|
|
21
|
+
* name, on the assumption the root sorts first. That assumption is false for any
|
|
22
|
+
* workspace glob outside `packages/*` — `apps/*` and `libs/*` sort a workspace
|
|
23
|
+
* package ahead of the root — so a project pinning `typescript ^5.7.2` recorded
|
|
24
|
+
* the workspace's `^5.4.0` instead. Measured 2026-11-16. Reading the manifest
|
|
25
|
+
* directly removes the ordering dependency entirely: whichever rows exist, the
|
|
26
|
+
* recorded specifier is the one the project itself declares.
|
|
27
|
+
*
|
|
28
|
+
* `null` means "cannot tell" — the manifest is absent, is not a JSON object, or
|
|
29
|
+
* could not be read — and the caller then falls back to the raw scan instead of
|
|
30
|
+
* emptying the map. A malformed manifest therefore degrades the same way a
|
|
31
|
+
* missing one does; it does not throw out of a refresh nobody explicitly asked
|
|
32
|
+
* for.
|
|
33
|
+
*/
|
|
34
|
+
export declare function rootDeclaredVersions(projectRoot: string): Map<string, string> | null;
|
|
35
|
+
/**
|
|
36
|
+
* The names the project's OWN `package.json` declares, across every scope.
|
|
37
|
+
* See `rootDeclaredVersions` for what `null` means.
|
|
38
|
+
*/
|
|
39
|
+
export declare function rootDeclaredNames(projectRoot: string): Set<string> | null;
|
|
40
|
+
/**
|
|
41
|
+
* Keep one row per name, and only for names the root manifest declares — a name
|
|
42
|
+
* only a workspace package declares is dropped, because the file describes the
|
|
43
|
+
* project and listing a dependency it does not have is a fact peaks-rd would then
|
|
44
|
+
* check against the wrong thing.
|
|
45
|
+
*/
|
|
46
|
+
export declare function toLibraryVersions(entries: ReadonlyArray<{
|
|
47
|
+
readonly name: string;
|
|
48
|
+
readonly version: string;
|
|
49
|
+
}>, rootDeclared: ReadonlySet<string>): Record<string, string>;
|
|
50
|
+
/**
|
|
51
|
+
* The map for a project.
|
|
52
|
+
*
|
|
53
|
+
* The ROOT MANIFEST supplies the specifier for every name it declares; the scan
|
|
54
|
+
* supplies only the row set. When the manifest cannot be read, the scan's own
|
|
55
|
+
* rows are used unchanged (never silently empties the map).
|
|
56
|
+
*/
|
|
57
|
+
export declare function libraryVersionsFor(projectRoot: string, entries: ReadonlyArray<{
|
|
58
|
+
readonly name: string;
|
|
59
|
+
readonly version: string;
|
|
60
|
+
}>): Record<string, string>;
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `libraryVersions` map a project scan records, derived from `scanLibraries`.
|
|
3
|
+
*
|
|
4
|
+
* WHY THE ROOT MANIFEST DECIDES. In a monorepo the scan concatenates every
|
|
5
|
+
* workspace `package.json`, so one name appears once per declaring package with
|
|
6
|
+
* that package's own spec — `typescript` arrives as BOTH the root's `^5.7.2` and
|
|
7
|
+
* a workspace package's `^5.4.0`, and a package used only by a workspace
|
|
8
|
+
* (`ecc-universal`) appears with no root declaration at all. Taking the first row
|
|
9
|
+
* records whichever specifier sorts first, which is the workspace's, not the
|
|
10
|
+
* project's. peaks-rd cross-checks this map against the breaking-changes table,
|
|
11
|
+
* and a floor is exactly the wrong version to file a project under.
|
|
12
|
+
*
|
|
13
|
+
* Split out of `project-scan-field-refresh.ts` to stay under the `src/**`
|
|
14
|
+
* 300-line cap.
|
|
15
|
+
*/
|
|
16
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
17
|
+
import { join } from 'node:path';
|
|
18
|
+
/** The `package.json` scopes a dependency can be declared in. */
|
|
19
|
+
const DEPENDENCY_SCOPES = [
|
|
20
|
+
'dependencies',
|
|
21
|
+
'devDependencies',
|
|
22
|
+
'peerDependencies',
|
|
23
|
+
'optionalDependencies'
|
|
24
|
+
];
|
|
25
|
+
/** A parsed `package.json` that carries dependency maps, or `null`. */
|
|
26
|
+
function isDependencyRecord(value) {
|
|
27
|
+
return value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Parse the root manifest. Returns `undefined` when it cannot be used — absent,
|
|
31
|
+
* unreadable, or not a JSON object.
|
|
32
|
+
*
|
|
33
|
+
* The catch does not RETURN the failure value: it records the failure in a
|
|
34
|
+
* variable and falls off the end, so the "cannot tell" answer is written once,
|
|
35
|
+
* at the call site, rather than disguised as a successful `return null`.
|
|
36
|
+
*/
|
|
37
|
+
function parseManifest(projectRoot) {
|
|
38
|
+
const manifestPath = join(projectRoot, 'package.json');
|
|
39
|
+
if (!existsSync(manifestPath))
|
|
40
|
+
return undefined;
|
|
41
|
+
let raw;
|
|
42
|
+
try {
|
|
43
|
+
raw = readFileSync(manifestPath, 'utf8');
|
|
44
|
+
}
|
|
45
|
+
catch {
|
|
46
|
+
raw = undefined;
|
|
47
|
+
}
|
|
48
|
+
if (raw === undefined)
|
|
49
|
+
return undefined;
|
|
50
|
+
let parsed;
|
|
51
|
+
try {
|
|
52
|
+
parsed = JSON.parse(raw);
|
|
53
|
+
}
|
|
54
|
+
catch {
|
|
55
|
+
parsed = undefined;
|
|
56
|
+
}
|
|
57
|
+
return isDependencyRecord(parsed) ? parsed : undefined;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* The root manifest's own dependency map: name → specifier, across every scope.
|
|
61
|
+
*
|
|
62
|
+
* THE ROOT MANIFEST IS THE SOURCE OF THE SPECIFIER, not the scan's row order.
|
|
63
|
+
* This used to be built by taking the first row `scanLibraries` emitted for each
|
|
64
|
+
* name, on the assumption the root sorts first. That assumption is false for any
|
|
65
|
+
* workspace glob outside `packages/*` — `apps/*` and `libs/*` sort a workspace
|
|
66
|
+
* package ahead of the root — so a project pinning `typescript ^5.7.2` recorded
|
|
67
|
+
* the workspace's `^5.4.0` instead. Measured 2026-11-16. Reading the manifest
|
|
68
|
+
* directly removes the ordering dependency entirely: whichever rows exist, the
|
|
69
|
+
* recorded specifier is the one the project itself declares.
|
|
70
|
+
*
|
|
71
|
+
* `null` means "cannot tell" — the manifest is absent, is not a JSON object, or
|
|
72
|
+
* could not be read — and the caller then falls back to the raw scan instead of
|
|
73
|
+
* emptying the map. A malformed manifest therefore degrades the same way a
|
|
74
|
+
* missing one does; it does not throw out of a refresh nobody explicitly asked
|
|
75
|
+
* for.
|
|
76
|
+
*/
|
|
77
|
+
export function rootDeclaredVersions(projectRoot) {
|
|
78
|
+
const parsed = parseManifest(projectRoot);
|
|
79
|
+
if (parsed === undefined)
|
|
80
|
+
return null;
|
|
81
|
+
const versions = new Map();
|
|
82
|
+
for (const scope of DEPENDENCY_SCOPES) {
|
|
83
|
+
const deps = parsed[scope];
|
|
84
|
+
if (!isDependencyRecord(deps))
|
|
85
|
+
continue;
|
|
86
|
+
for (const [name, spec] of Object.entries(deps)) {
|
|
87
|
+
// A scope earlier in DEPENDENCY_SCOPES wins, matching package.json's own
|
|
88
|
+
// precedence (a real `dependency` is what the project installs).
|
|
89
|
+
if (!versions.has(name) && typeof spec === 'string')
|
|
90
|
+
versions.set(name, spec);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
return versions;
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* The names the project's OWN `package.json` declares, across every scope.
|
|
97
|
+
* See `rootDeclaredVersions` for what `null` means.
|
|
98
|
+
*/
|
|
99
|
+
export function rootDeclaredNames(projectRoot) {
|
|
100
|
+
const versions = rootDeclaredVersions(projectRoot);
|
|
101
|
+
return versions === null ? null : new Set(versions.keys());
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* Keep one row per name, and only for names the root manifest declares — a name
|
|
105
|
+
* only a workspace package declares is dropped, because the file describes the
|
|
106
|
+
* project and listing a dependency it does not have is a fact peaks-rd would then
|
|
107
|
+
* check against the wrong thing.
|
|
108
|
+
*/
|
|
109
|
+
export function toLibraryVersions(entries, rootDeclared) {
|
|
110
|
+
const versions = {};
|
|
111
|
+
for (const entry of entries) {
|
|
112
|
+
if (!rootDeclared.has(entry.name))
|
|
113
|
+
continue;
|
|
114
|
+
if (versions[entry.name] === undefined)
|
|
115
|
+
versions[entry.name] = entry.version;
|
|
116
|
+
}
|
|
117
|
+
return versions;
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* The map for a project.
|
|
121
|
+
*
|
|
122
|
+
* The ROOT MANIFEST supplies the specifier for every name it declares; the scan
|
|
123
|
+
* supplies only the row set. When the manifest cannot be read, the scan's own
|
|
124
|
+
* rows are used unchanged (never silently empties the map).
|
|
125
|
+
*/
|
|
126
|
+
export function libraryVersionsFor(projectRoot, entries) {
|
|
127
|
+
const declared = rootDeclaredVersions(projectRoot);
|
|
128
|
+
if (declared === null) {
|
|
129
|
+
return toLibraryVersions(entries, new Set(entries.map((e) => e.name)));
|
|
130
|
+
}
|
|
131
|
+
const versions = {};
|
|
132
|
+
for (const [name, spec] of declared)
|
|
133
|
+
versions[name] = spec;
|
|
134
|
+
return versions;
|
|
135
|
+
}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `techStack` snapshot a project scan records, derived from the project's
|
|
3
|
+
* own `package.json` plus its lockfile sentinels.
|
|
4
|
+
*
|
|
5
|
+
* WHY IT IS DERIVED AND NOT WRITTEN AS A LITERAL. The create path used to
|
|
6
|
+
* hard-code `techStack: {}` and a `Language | TypeScript (best-effort — re-confirm
|
|
7
|
+
* via package.json devDeps)` table row, so the FIRST write was already
|
|
8
|
+
* uninformative and a refresh had nothing better to say. Every value here is read
|
|
9
|
+
* from the project, which is what makes a refresh worth running.
|
|
10
|
+
*
|
|
11
|
+
* Split out of `project-scan-field-refresh.ts` to stay under the `src/**`
|
|
12
|
+
* 300-line cap; the refresh path imports `deriveTechStack` from here.
|
|
13
|
+
*/
|
|
14
|
+
/** The `techStack` snapshot, derived from `package.json` + lockfile sentinels. */
|
|
15
|
+
export declare function deriveTechStack(projectRoot: string): Record<string, string>;
|
|
16
|
+
/**
|
|
17
|
+
* Merge a freshly derived snapshot into the one already on disk.
|
|
18
|
+
*
|
|
19
|
+
* WHY A REFRESH MERGES. `techStack` is the one managed field whose values a
|
|
20
|
+
* human also edits: a project owner routinely adds a row the derivation knows
|
|
21
|
+
* nothing about (`lintTool`, a pinned-version note), and rewrites `buildTool`
|
|
22
|
+
* into something more useful than the raw script. Rewriting the map wholesale
|
|
23
|
+
* would silently undo that on the next `peaks project context` — the same class
|
|
24
|
+
* of sediment loss the refresh exists to prevent on every other field.
|
|
25
|
+
*
|
|
26
|
+
* The rule, stated so it can be checked against the code:
|
|
27
|
+
* - a key the derivation produces → the derived value wins, EXCEPT when that
|
|
28
|
+
* value is a truncated build script and the file already carries a fuller
|
|
29
|
+
* one (`isTruncated` above: less information must not displace more);
|
|
30
|
+
* - a key the derivation CAN produce but did not → dropped (it is stale, not
|
|
31
|
+
* sediment — see DERIVED_KEYS);
|
|
32
|
+
* - any other key → carried over untouched (the derivation has no opinion).
|
|
33
|
+
*/
|
|
34
|
+
export declare function mergeTechStack(existing: Readonly<Record<string, string>>, derived: Readonly<Record<string, string>>): Record<string, string>;
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `techStack` snapshot a project scan records, derived from the project's
|
|
3
|
+
* own `package.json` plus its lockfile sentinels.
|
|
4
|
+
*
|
|
5
|
+
* WHY IT IS DERIVED AND NOT WRITTEN AS A LITERAL. The create path used to
|
|
6
|
+
* hard-code `techStack: {}` and a `Language | TypeScript (best-effort — re-confirm
|
|
7
|
+
* via package.json devDeps)` table row, so the FIRST write was already
|
|
8
|
+
* uninformative and a refresh had nothing better to say. Every value here is read
|
|
9
|
+
* from the project, which is what makes a refresh worth running.
|
|
10
|
+
*
|
|
11
|
+
* Split out of `project-scan-field-refresh.ts` to stay under the `src/**`
|
|
12
|
+
* 300-line cap; the refresh path imports `deriveTechStack` from here.
|
|
13
|
+
*/
|
|
14
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
15
|
+
import { join } from 'node:path';
|
|
16
|
+
import { z } from 'zod';
|
|
17
|
+
import { tryParseJson } from '../../shared/json-parse.js';
|
|
18
|
+
/** A derived build script longer than this is truncated in the snapshot. */
|
|
19
|
+
const BUILD_TOOL_MAX = 100;
|
|
20
|
+
/**
|
|
21
|
+
* The `package.json` keys this derivation reads, and nothing more.
|
|
22
|
+
* `looseObject` on purpose: a manifest carries far more than this reader
|
|
23
|
+
* consumes, and validation is not licence to reject the rest of the file.
|
|
24
|
+
*/
|
|
25
|
+
const packageManifestSchema = z.looseObject({
|
|
26
|
+
packageManager: z.string().optional(),
|
|
27
|
+
engines: z.looseObject({ node: z.string().optional() }).optional(),
|
|
28
|
+
scripts: z.looseObject({ build: z.string().optional() }).optional(),
|
|
29
|
+
dependencies: z.record(z.string(), z.string()).optional(),
|
|
30
|
+
devDependencies: z.record(z.string(), z.string()).optional()
|
|
31
|
+
});
|
|
32
|
+
/** Lockfiles in precedence order — the first one present names the manager. */
|
|
33
|
+
const LOCKFILE_PACKAGE_MANAGERS = [
|
|
34
|
+
['pnpm-lock.yaml', 'pnpm'],
|
|
35
|
+
['package-lock.json', 'npm'],
|
|
36
|
+
['yarn.lock', 'yarn'],
|
|
37
|
+
['bun.lockb', 'bun']
|
|
38
|
+
];
|
|
39
|
+
function readManifestText(manifestPath) {
|
|
40
|
+
let text;
|
|
41
|
+
try {
|
|
42
|
+
text = readFileSync(manifestPath, 'utf8');
|
|
43
|
+
}
|
|
44
|
+
catch {
|
|
45
|
+
text = undefined;
|
|
46
|
+
}
|
|
47
|
+
return text;
|
|
48
|
+
}
|
|
49
|
+
function readManifest(projectRoot) {
|
|
50
|
+
const manifestPath = join(projectRoot, 'package.json');
|
|
51
|
+
if (!existsSync(manifestPath))
|
|
52
|
+
return null;
|
|
53
|
+
// A malformed — or unreadable — manifest is a soft signal, not a failure:
|
|
54
|
+
// `scanLibraries` already reports it as a warning, and the snapshot degrades to
|
|
55
|
+
// the fields that need no manifest rather than failing the whole refresh.
|
|
56
|
+
// Measured 2026-11-16: an unreadable `package.json` (e.g. a directory of that
|
|
57
|
+
// name) threw EISDIR out of `peaks project context`, which is an everyday
|
|
58
|
+
// command and must not fail over a scan snapshot nobody asked for.
|
|
59
|
+
const raw = readManifestText(manifestPath);
|
|
60
|
+
if (raw === undefined)
|
|
61
|
+
return null;
|
|
62
|
+
const parsed = tryParseJson(raw, packageManifestSchema);
|
|
63
|
+
return parsed.ok ? parsed.value : null;
|
|
64
|
+
}
|
|
65
|
+
function detectLanguage(projectRoot, manifest) {
|
|
66
|
+
const declaresTypeScript = manifest?.devDependencies?.['typescript'] !== undefined ||
|
|
67
|
+
manifest?.dependencies?.['typescript'] !== undefined;
|
|
68
|
+
return declaresTypeScript || existsSync(join(projectRoot, 'tsconfig.json'))
|
|
69
|
+
? 'typescript'
|
|
70
|
+
: 'javascript';
|
|
71
|
+
}
|
|
72
|
+
function detectPackageManager(projectRoot, manifest) {
|
|
73
|
+
const declared = manifest?.packageManager;
|
|
74
|
+
if (declared !== undefined)
|
|
75
|
+
return declared;
|
|
76
|
+
for (const [lockfile, packageManager] of LOCKFILE_PACKAGE_MANAGERS) {
|
|
77
|
+
if (existsSync(join(projectRoot, lockfile)))
|
|
78
|
+
return packageManager;
|
|
79
|
+
}
|
|
80
|
+
return 'unknown';
|
|
81
|
+
}
|
|
82
|
+
/** `node>=24.0.0 (active v24.12.0)` — the floor from `engines`, plus the
|
|
83
|
+
* runtime the snapshot was taken on. */
|
|
84
|
+
function detectRuntime(manifest) {
|
|
85
|
+
const active = process.versions.node;
|
|
86
|
+
const floor = manifest?.engines?.node;
|
|
87
|
+
return floor === undefined ? `node v${active}` : `node${floor} (active v${active})`;
|
|
88
|
+
}
|
|
89
|
+
function detectBuildTool(manifest) {
|
|
90
|
+
const build = manifest?.scripts?.build;
|
|
91
|
+
if (build === undefined)
|
|
92
|
+
return null;
|
|
93
|
+
return build.length <= BUILD_TOOL_MAX ? build : `${build.slice(0, BUILD_TOOL_MAX)}…`;
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* True when the derived value is a TRUNCATED build script — a value that records
|
|
97
|
+
* "there is a build script, and it starts like this", not what the build is.
|
|
98
|
+
*
|
|
99
|
+
* WHY THIS MATTERS. `buildTool` is the one derived key a project owner
|
|
100
|
+
* realistically rewrites: a hand-written `tsc -p tsconfig.build.json` says what
|
|
101
|
+
* the build IS, while the derived value is the raw `scripts.build` cut at 100
|
|
102
|
+
* chars. Measured 2026-11-16 on this repository: a refresh replaced that owner
|
|
103
|
+
* line with
|
|
104
|
+
* `node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && pnpm -r --filter "./packages/*" …`.
|
|
105
|
+
* A truncated value is strictly LESS informative than the line it would replace,
|
|
106
|
+
* so it yields to whatever is on disk.
|
|
107
|
+
*/
|
|
108
|
+
function isTruncated(buildTool) {
|
|
109
|
+
return buildTool.length > BUILD_TOOL_MAX;
|
|
110
|
+
}
|
|
111
|
+
/** The `techStack` snapshot, derived from `package.json` + lockfile sentinels. */
|
|
112
|
+
export function deriveTechStack(projectRoot) {
|
|
113
|
+
const manifest = readManifest(projectRoot);
|
|
114
|
+
const techStack = {
|
|
115
|
+
language: detectLanguage(projectRoot, manifest),
|
|
116
|
+
packageManager: detectPackageManager(projectRoot, manifest),
|
|
117
|
+
runtime: detectRuntime(manifest)
|
|
118
|
+
};
|
|
119
|
+
const buildTool = detectBuildTool(manifest);
|
|
120
|
+
if (buildTool !== null)
|
|
121
|
+
techStack['buildTool'] = buildTool;
|
|
122
|
+
return techStack;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Every key `deriveTechStack` can ever emit. A key in this set that the current
|
|
126
|
+
* derivation did not produce is STALE — the machine fact it recorded has gone
|
|
127
|
+
* away — and must not be carried over. This is the second half of the merge:
|
|
128
|
+
* without it, a project that deletes its `scripts.build` would have the old
|
|
129
|
+
* `buildTool` rewritten back on every refresh, forever, from a machine value
|
|
130
|
+
* that no longer has a source.
|
|
131
|
+
*/
|
|
132
|
+
const DERIVED_KEYS = new Set([
|
|
133
|
+
'language',
|
|
134
|
+
'packageManager',
|
|
135
|
+
'runtime',
|
|
136
|
+
'buildTool'
|
|
137
|
+
]);
|
|
138
|
+
/**
|
|
139
|
+
* Merge a freshly derived snapshot into the one already on disk.
|
|
140
|
+
*
|
|
141
|
+
* WHY A REFRESH MERGES. `techStack` is the one managed field whose values a
|
|
142
|
+
* human also edits: a project owner routinely adds a row the derivation knows
|
|
143
|
+
* nothing about (`lintTool`, a pinned-version note), and rewrites `buildTool`
|
|
144
|
+
* into something more useful than the raw script. Rewriting the map wholesale
|
|
145
|
+
* would silently undo that on the next `peaks project context` — the same class
|
|
146
|
+
* of sediment loss the refresh exists to prevent on every other field.
|
|
147
|
+
*
|
|
148
|
+
* The rule, stated so it can be checked against the code:
|
|
149
|
+
* - a key the derivation produces → the derived value wins, EXCEPT when that
|
|
150
|
+
* value is a truncated build script and the file already carries a fuller
|
|
151
|
+
* one (`isTruncated` above: less information must not displace more);
|
|
152
|
+
* - a key the derivation CAN produce but did not → dropped (it is stale, not
|
|
153
|
+
* sediment — see DERIVED_KEYS);
|
|
154
|
+
* - any other key → carried over untouched (the derivation has no opinion).
|
|
155
|
+
*/
|
|
156
|
+
export function mergeTechStack(existing, derived) {
|
|
157
|
+
const carried = Object.fromEntries(Object.entries(existing).filter(([key]) => !DERIVED_KEYS.has(key)));
|
|
158
|
+
const onDiskBuildTool = existing['buildTool'];
|
|
159
|
+
const derivedBuildTool = derived['buildTool'];
|
|
160
|
+
const keepsOwnerBuildTool = onDiskBuildTool !== undefined &&
|
|
161
|
+
derivedBuildTool !== undefined &&
|
|
162
|
+
isTruncated(derivedBuildTool) &&
|
|
163
|
+
onDiskBuildTool !== derivedBuildTool;
|
|
164
|
+
if (!keepsOwnerBuildTool)
|
|
165
|
+
return { ...carried, ...derived };
|
|
166
|
+
return { ...carried, ...derived, buildTool: onDiskBuildTool };
|
|
167
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "peaks-loop",
|
|
3
|
-
"version": "4.2.
|
|
3
|
+
"version": "4.2.2",
|
|
4
4
|
"description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
|
|
5
5
|
"author": "SquabbyZ",
|
|
6
6
|
"keywords": [
|
|
@@ -133,11 +133,11 @@
|
|
|
133
133
|
"picomatch": "4.0.7",
|
|
134
134
|
"yaml": "^2.9.1",
|
|
135
135
|
"zod": "^4.6.7",
|
|
136
|
-
"peaks-loop-internal-runtime": "0.0.
|
|
137
|
-
"peaks-loop-
|
|
138
|
-
"peaks-loop-shared
|
|
139
|
-
"peaks-loop-workspace-runtime": "0.0.
|
|
140
|
-
"peaks-loop-
|
|
136
|
+
"peaks-loop-internal-runtime": "0.0.69",
|
|
137
|
+
"peaks-loop-mut": "0.1.83",
|
|
138
|
+
"peaks-loop-shared": "0.0.118",
|
|
139
|
+
"peaks-loop-workspace-runtime": "0.0.3",
|
|
140
|
+
"peaks-loop-shared-channel": "0.0.86"
|
|
141
141
|
},
|
|
142
142
|
"devDependencies": {
|
|
143
143
|
"@changesets/cli": "2.31.1",
|
|
@@ -248,7 +248,7 @@ Step 0 creates the workspace; all intermediate artifacts land under `.peaks/_run
|
|
|
248
248
|
|
|
249
249
|
## Peaks-Loop Pre-RD project scan checklist (MANDATORY)
|
|
250
250
|
|
|
251
|
-
Before handing off to `peaks-rd`, scan the project and record findings to `.peaks/project-scan/project-scan.md` (project-level, git-tracked; sibling of `.peaks/PROJECT.md`). Slice 2026-07-15-project-scan-bootstrap (G1 + G2): `peaks workspace init` and `peaks project context` both bootstrap this file automatically; only re-run the manual flow when the
|
|
251
|
+
Before handing off to `peaks-rd`, scan the project and record findings to `.peaks/project-scan/project-scan.md` (project-level, git-tracked; sibling of `.peaks/PROJECT.md`). Slice 2026-07-15-project-scan-bootstrap (G1 + G2): `peaks workspace init` and `peaks project context` both bootstrap this file automatically. `peaks project context` also refreshes its machine fields (`capturedAt` / `techStack` / `libraryVersions`) in place on every run, leaving the prose alone; only re-run the manual flow when the SCAN ITSELF (archetype / project mode) is genuinely out of date. → `references/project-scan-checklist.md`.
|
|
252
252
|
|
|
253
253
|
> **Slice 2026-07-15-project-scan-bootstrap G4b / AC9:** after `peaks workspace init`, the consumer project's `.peaks/project-scan/` directory carries 5 files: `project-scan.md` (generated by the scan logic) + `business-knowledge.md` + `security-template.md` + `perf-template.md` + `audit-output-schema.md` (the 4 audit/business templates bundled at `src/services/workspace/templates/project-scan/*.md`, copied on init; idempotent — existing files preserved unless `--force-project-scan-templates`). RD / UI / TXT / QA read from this tree; nothing else.
|
|
254
254
|
|
|
@@ -4,7 +4,9 @@
|
|
|
4
4
|
|
|
5
5
|
Before handing off to `peaks-rd`, scan the project and record findings to `.peaks/project-scan/project-scan.md` (project-level, git-tracked; sibling of `.peaks/PROJECT.md`). RD and UI roles read this before starting work. **project-scan.md is a project-scoped singleton** — check if it already exists before regenerating (e.g. via `ls .peaks/project-scan/project-scan.md`). If it exists and is complete (has `## Archetype` and `## Project mode` sections), reuse it. Only regenerate if missing or incomplete.
|
|
6
6
|
|
|
7
|
-
> **Slice 2026-07-15-project-scan-bootstrap (G1 + G2 + G4b):** `peaks workspace init` and `peaks project context` now both bootstrap `.peaks/project-scan/project-scan.md` automatically. On a brand-new 0-1 project (no `package.json` or no source files) the file is seeded with `archetype: unknown` + `(empty)` placeholder rows. On an existing project it is filled from `peaks scan archetype` + `peaks scan libraries` output.
|
|
7
|
+
> **Slice 2026-07-15-project-scan-bootstrap (G1 + G2 + G4b):** `peaks workspace init` and `peaks project context` now both bootstrap `.peaks/project-scan/project-scan.md` automatically. On a brand-new 0-1 project (no `package.json` or no source files) the file is seeded with `archetype: unknown` + `(empty)` placeholder rows. On an existing project it is filled from `peaks scan archetype` + `peaks scan libraries` output.
|
|
8
|
+
>
|
|
9
|
+
> **Refresh semantics (2026-11-15):** the file is never REGENERATED once it exists — its markdown body is sediment. What a refresh does is rewrite only its three machine-derivable frontmatter fields (`capturedAt`, `techStack`, `libraryVersions`) in place, preserving every other byte. `peaks project context --project <repo>` does that by default; `--no-project-scan-refresh` opts out. A file that was never populated (empty `architecture` AND empty `techStack`) is filled automatically, because it carries no sediment to protect. `peaks workspace init` keeps its skip semantics, and `--force-project-scan-templates` governs only the 4 bundled audit/business templates.
|
|
8
10
|
|
|
9
11
|
### 0. Project archetype detection (MANDATORY — run FIRST, deterministic CLI)
|
|
10
12
|
|