@phren/cli 0.1.41 → 0.1.44
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/capabilities/cli.js +1 -1
- package/dist/capabilities/mcp.js +1 -1
- package/dist/capabilities/vscode.js +3 -3
- package/dist/capabilities/web-ui.js +29 -29
- package/dist/cli/actions.js +1 -13
- package/dist/cli/extract.js +3 -2
- package/dist/cli/hooks-output.js +15 -6
- package/dist/cli/hooks.js +2 -2
- package/dist/cli/namespaces-utils.js +1 -1
- package/dist/content/archive.js +3 -2
- package/dist/content/dedup.js +4 -3
- package/dist/content/learning.js +5 -4
- package/dist/content/secrets.js +4 -1
- package/dist/data/access.js +10 -9
- package/dist/data/tasks.js +46 -6
- package/dist/finding/lifecycle.js +3 -2
- package/dist/governance/policy.js +4 -3
- package/dist/governance/scores.d.ts +9 -1
- package/dist/governance/scores.js +12 -1
- package/dist/init/init-uninstall.js +12 -2
- package/dist/profile-store.d.ts +2 -0
- package/dist/profile-store.js +13 -17
- package/dist/project-config.js +3 -2
- package/dist/project-topics.js +13 -12
- package/dist/shared/data-utils.js +13 -3
- package/dist/shared/fragment-graph.js +7 -2
- package/dist/shared/retrieval.d.ts +10 -0
- package/dist/shared/retrieval.js +17 -4
- package/dist/shell/entry.d.ts +8 -0
- package/dist/shell/entry.js +114 -58
- package/dist/shell/input.d.ts +1 -1
- package/dist/shell/input.js +4 -1
- package/dist/shell/keys.d.ts +36 -0
- package/dist/shell/keys.js +107 -0
- package/dist/shell/render.d.ts +33 -0
- package/dist/shell/render.js +216 -46
- package/dist/shell/shell.js +16 -3
- package/dist/shell/view.js +2 -1
- package/dist/store-registry.d.ts +13 -0
- package/dist/store-registry.js +106 -34
- package/dist/store-routing.d.ts +8 -0
- package/dist/store-routing.js +23 -1
- package/dist/tools/config.js +4 -3
- package/dist/tools/extract-facts.js +3 -2
- package/dist/tools/finding.js +6 -5
- package/dist/tools/memory.js +12 -5
- package/dist/tools/ops.js +1 -1
- package/dist/ui/server.js +2 -6
- package/dist/utils-fts.js +3 -2
- package/dist/utils-paths.d.ts +1 -0
- package/dist/utils-paths.js +1 -1
- package/dist/utils.d.ts +1 -1
- package/dist/utils.js +1 -1
- package/package.json +31 -4
- package/starter/global/skills/phren-consolidate/SKILL.md +152 -0
- package/starter/global/skills/phren-discover/SKILL.md +175 -0
- package/starter/global/skills/phren-init/SKILL.md +216 -0
- package/starter/global/skills/phren-profiles/SKILL.md +121 -0
- package/starter/global/skills/phren-sync/SKILL.md +261 -0
- package/dist/init-uninstall.d.ts +0 -3
- package/dist/init-uninstall.js +0 -514
- package/dist/init-walkthrough.d.ts +0 -55
- package/dist/init-walkthrough.js +0 -524
package/dist/tools/config.js
CHANGED
|
@@ -7,7 +7,8 @@ import { PROACTIVITY_LEVELS, } from "../proactivity.js";
|
|
|
7
7
|
import { writeGovernanceInstallPreferences, } from "../init/preferences.js";
|
|
8
8
|
import { FINDING_SENSITIVITY_CONFIG, buildProactivitySnapshot, checkProjectInProfile } from "../cli/config.js";
|
|
9
9
|
import { readProjectConfig, updateProjectConfigOverrides, } from "../project-config.js";
|
|
10
|
-
import { errorMessage, isValidProjectName
|
|
10
|
+
import { errorMessage, isValidProjectName } from "../utils.js";
|
|
11
|
+
import { storeAwareProjectPath } from "../store-routing.js";
|
|
11
12
|
import { ACCESS_ROLE_KEYS, ACL_LOCKOUT_HINT, permissionDeniedError, setAccessRoles } from "../governance/rbac.js";
|
|
12
13
|
import { readProjectTopics, writeProjectTopics, } from "../project-topics.js";
|
|
13
14
|
import { buildConfigView } from "../config/resolve.js";
|
|
@@ -41,7 +42,7 @@ function hasOwnOverride(overrides, key) {
|
|
|
41
42
|
const projectParam = z.string().optional().describe("Project name. When provided, writes to that project's phren.project.yaml instead of global .config/.");
|
|
42
43
|
// ── Topic helpers (shared by get_config topic domain and set_config topic domain) ──
|
|
43
44
|
function getTopicConfigData(phrenPath, project) {
|
|
44
|
-
const projectDir =
|
|
45
|
+
const projectDir = storeAwareProjectPath(phrenPath, project);
|
|
45
46
|
if (!projectDir || !fs.existsSync(projectDir)) {
|
|
46
47
|
return { ok: false, error: `Project "${project}" not found in phren.` };
|
|
47
48
|
}
|
|
@@ -533,7 +534,7 @@ async function handleSetConfig(ctx, { domain, settings, project }) {
|
|
|
533
534
|
catch (err) {
|
|
534
535
|
return mcpResponse({ ok: false, error: errorMessage(err) });
|
|
535
536
|
}
|
|
536
|
-
const projectDir =
|
|
537
|
+
const projectDir = storeAwareProjectPath(topicPhrenPath, topicProject);
|
|
537
538
|
if (!projectDir || !fs.existsSync(projectDir)) {
|
|
538
539
|
return mcpResponse({ ok: false, error: `Project "${topicProject}" not found in phren.` });
|
|
539
540
|
}
|
|
@@ -7,14 +7,15 @@
|
|
|
7
7
|
import * as fs from "fs";
|
|
8
8
|
import * as path from "path";
|
|
9
9
|
import { debugLog } from "../shared.js";
|
|
10
|
-
import {
|
|
10
|
+
import { isFeatureEnabled, errorMessage } from "../utils.js";
|
|
11
|
+
import { storeAwareProjectPath } from "../store-routing.js";
|
|
11
12
|
import { callLlm } from "../content/dedup.js";
|
|
12
13
|
import { withFileLock } from "../shared/governance.js";
|
|
13
14
|
import { logger } from "../logger.js";
|
|
14
15
|
const FACT_EXTRACT_FLAG = "PHREN_FEATURE_FACT_EXTRACT";
|
|
15
16
|
const MAX_FACTS = 50;
|
|
16
17
|
function preferencesPath(phrenPath, project) {
|
|
17
|
-
const dir =
|
|
18
|
+
const dir = storeAwareProjectPath(phrenPath, project);
|
|
18
19
|
return dir ? path.join(dir, "preferences.json") : null;
|
|
19
20
|
}
|
|
20
21
|
export function readExtractedFacts(phrenPath, project) {
|
package/dist/tools/finding.js
CHANGED
|
@@ -3,7 +3,8 @@ import { z } from "zod";
|
|
|
3
3
|
import * as fs from "fs";
|
|
4
4
|
import * as path from "path";
|
|
5
5
|
import { logger } from "../logger.js";
|
|
6
|
-
import { isValidProjectName,
|
|
6
|
+
import { isValidProjectName, errorMessage } from "../utils.js";
|
|
7
|
+
import { storeAwareProjectPath } from "../store-routing.js";
|
|
7
8
|
import { removeFinding as removeFindingCore, removeFindings as removeFindingsCore, applyFindingTypePrefix, } from "../core/finding.js";
|
|
8
9
|
import { debugLog, EXEC_TIMEOUT_MS, FINDING_TYPES, normalizeMemoryScope, } from "../shared.js";
|
|
9
10
|
import { getCurrentActor, getMachineName } from "../machine-identity.js";
|
|
@@ -101,7 +102,7 @@ function withLifecycleMutation(phrenPath, project, writeQueue, updateIndex, hand
|
|
|
101
102
|
const result = handler();
|
|
102
103
|
if (!result.ok)
|
|
103
104
|
return mcpResponse({ ok: false, error: result.error });
|
|
104
|
-
const resolvedFindingsDir =
|
|
105
|
+
const resolvedFindingsDir = storeAwareProjectPath(phrenPath, project);
|
|
105
106
|
if (resolvedFindingsDir)
|
|
106
107
|
updateIndex(path.join(resolvedFindingsDir, FINDINGS_FILENAME));
|
|
107
108
|
const mapped = mapResponse(result.data);
|
|
@@ -445,7 +446,7 @@ async function handleEditFinding(ctx, { project: projectInput, old_text, new_tex
|
|
|
445
446
|
const result = editFindingCore(phrenPath, project, old_text, new_text);
|
|
446
447
|
if (!result.ok)
|
|
447
448
|
return mcpResponse({ ok: false, error: result.error });
|
|
448
|
-
const resolvedFindingsDir =
|
|
449
|
+
const resolvedFindingsDir = storeAwareProjectPath(phrenPath, project);
|
|
449
450
|
if (resolvedFindingsDir)
|
|
450
451
|
updateFileInIndex(path.join(resolvedFindingsDir, FINDINGS_FILENAME));
|
|
451
452
|
return mcpResponse({
|
|
@@ -477,7 +478,7 @@ async function handleRemoveFinding(ctx, { project: projectInput, finding }) {
|
|
|
477
478
|
const result = removeFindingsCore(phrenPath, project, finding);
|
|
478
479
|
if (!result.ok)
|
|
479
480
|
return mcpResponse({ ok: false, error: result.message });
|
|
480
|
-
const resolvedFindingsDir =
|
|
481
|
+
const resolvedFindingsDir = storeAwareProjectPath(phrenPath, project);
|
|
481
482
|
if (resolvedFindingsDir)
|
|
482
483
|
updateFileInIndex(path.join(resolvedFindingsDir, FINDINGS_FILENAME));
|
|
483
484
|
return mcpResponse({ ok: true, message: result.message, data: result.data });
|
|
@@ -487,7 +488,7 @@ async function handleRemoveFinding(ctx, { project: projectInput, finding }) {
|
|
|
487
488
|
const result = removeFindingCore(phrenPath, project, finding);
|
|
488
489
|
if (!result.ok)
|
|
489
490
|
return mcpResponse({ ok: false, error: result.message });
|
|
490
|
-
const resolvedFindingsDir =
|
|
491
|
+
const resolvedFindingsDir = storeAwareProjectPath(phrenPath, project);
|
|
491
492
|
if (resolvedFindingsDir)
|
|
492
493
|
updateFileInIndex(path.join(resolvedFindingsDir, FINDINGS_FILENAME));
|
|
493
494
|
return mcpResponse({ ok: true, message: result.message, data: result.data });
|
package/dist/tools/memory.js
CHANGED
|
@@ -6,6 +6,12 @@ import { runtimeDir } from "../shared.js";
|
|
|
6
6
|
import { recordFeedback, flushEntryScores, } from "../shared/governance.js";
|
|
7
7
|
import { upsertCanonical } from "../shared/content.js";
|
|
8
8
|
import { isValidProjectName } from "../utils.js";
|
|
9
|
+
import { storeAwareProjectPath } from "../store-routing.js";
|
|
10
|
+
/** truths.md path via the same store-aware routing upsertCanonical writes with. */
|
|
11
|
+
function truthsFilePath(phrenPath, project) {
|
|
12
|
+
return storeAwareProjectPath(phrenPath, project, "truths.md")
|
|
13
|
+
?? path.join(phrenPath, project, "truths.md");
|
|
14
|
+
}
|
|
9
15
|
export function register(server, ctx) {
|
|
10
16
|
const { withWriteQueue, updateFileInIndex } = ctx;
|
|
11
17
|
server.registerTool("pin_memory", {
|
|
@@ -32,8 +38,7 @@ export function register(server, ctx) {
|
|
|
32
38
|
const result = upsertCanonical(phrenPath, project, memory);
|
|
33
39
|
if (!result.ok)
|
|
34
40
|
return mcpResponse({ ok: false, error: result.error });
|
|
35
|
-
|
|
36
|
-
updateFileInIndex(canonicalPath);
|
|
41
|
+
updateFileInIndex(truthsFilePath(phrenPath, project));
|
|
37
42
|
return mcpResponse({ ok: true, message: result.data, data: { project, memory } });
|
|
38
43
|
});
|
|
39
44
|
});
|
|
@@ -56,7 +61,7 @@ export function register(server, ctx) {
|
|
|
56
61
|
}
|
|
57
62
|
if (!isValidProjectName(project))
|
|
58
63
|
return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
|
|
59
|
-
const truthsPath =
|
|
64
|
+
const truthsPath = truthsFilePath(phrenPath, project);
|
|
60
65
|
if (!fs.existsSync(truthsPath)) {
|
|
61
66
|
return mcpResponse({ ok: true, message: `No truths pinned for "${project}" yet.`, data: { project, truths: [], count: 0 } });
|
|
62
67
|
}
|
|
@@ -74,9 +79,11 @@ export function register(server, ctx) {
|
|
|
74
79
|
});
|
|
75
80
|
server.registerTool("memory_feedback", {
|
|
76
81
|
title: "◆ phren · feedback",
|
|
77
|
-
description: "Record feedback on whether an injected memory was helpful or noisy/regressive."
|
|
82
|
+
description: "Record feedback on whether an injected memory was helpful or noisy/regressive. " +
|
|
83
|
+
"The key is printed in <phren-context> snippet headers as `fb:<project>/<file>:<digest>` — pass that token (with or without the `fb:` prefix). " +
|
|
84
|
+
"Feedback adjusts that memory's ranking weight in future injections.",
|
|
78
85
|
inputSchema: z.object({
|
|
79
|
-
key: z.string().describe("
|
|
86
|
+
key: z.string().describe("Feedback key from an injected snippet header, e.g. `fb:myproj/FINDINGS.md:a1b2c3d4e5f6` or `myproj/FINDINGS.md:a1b2c3d4e5f6`."),
|
|
80
87
|
feedback: z.enum(["helpful", "reprompt", "regression"]).describe("Feedback type."),
|
|
81
88
|
}),
|
|
82
89
|
}, async ({ key, feedback }) => {
|
package/dist/tools/ops.js
CHANGED
|
@@ -494,7 +494,7 @@ export function register(server, ctx) {
|
|
|
494
494
|
}, (params) => handleGetReviewQueue(ctx, params));
|
|
495
495
|
server.registerTool("manage_review_item", {
|
|
496
496
|
title: "◆ phren · manage review item",
|
|
497
|
-
description: "Manage a review queue item: approve (
|
|
497
|
+
description: "Manage a review queue item: approve (PROMOTES the queued line into FINDINGS.md — if the finding is already present or archived it just dequeues), reject (removes from queue AND FINDINGS.md), or edit (updates text in both).",
|
|
498
498
|
inputSchema: z.object({
|
|
499
499
|
project: z.string().describe("Project name."),
|
|
500
500
|
line: z.string().max(10000).describe("The raw queue line text (as returned by get_review_queue)."),
|
package/dist/ui/server.js
CHANGED
|
@@ -15,7 +15,8 @@ import { buildGraph, collectProjectsForUI, collectSkillsForUI, getHooksData, isA
|
|
|
15
15
|
import { lookupEventsLogFile } from "../shared.js";
|
|
16
16
|
import { CONSOLIDATION_ENTRY_THRESHOLD } from "../content/validate.js";
|
|
17
17
|
import { ensureTopicReferenceDoc, getProjectTopicsResponse, listProjectReferenceDocs, pinProjectTopicSuggestion, readReferenceContent, reclassifyLegacyTopicDocs, unpinProjectTopicSuggestion, writeProjectTopics, } from "../project-topics.js";
|
|
18
|
-
import { getWorkflowPolicy, updateWorkflowPolicy, mergeConfig, getRetentionPolicy, getProjectConfigOverrides, getIndexPolicy, updateIndexPolicy, VALID_TASK_MODES } from "../governance/policy.js";
|
|
18
|
+
import { getWorkflowPolicy, updateWorkflowPolicy, updateRetentionPolicy, mergeConfig, getRetentionPolicy, getProjectConfigOverrides, getIndexPolicy, updateIndexPolicy, VALID_TASK_MODES } from "../governance/policy.js";
|
|
19
|
+
import { listProfiles, setMachineProfile, getDefaultMachineAlias } from "../profile-store.js";
|
|
19
20
|
import { setAccessRoles, ACCESS_ROLE_KEYS, permissionDeniedError } from "../governance/rbac.js";
|
|
20
21
|
import { readProjectConfig, updateProjectConfigOverrides } from "../project-config.js";
|
|
21
22
|
import { buildConfigView } from "../config/resolve.js";
|
|
@@ -1009,7 +1010,6 @@ function handlePostSettingsMcpEnabled(req, res, url, ctx) {
|
|
|
1009
1010
|
}
|
|
1010
1011
|
function handleGetProfiles(res, ctx) {
|
|
1011
1012
|
try {
|
|
1012
|
-
const { listProfiles } = require("../profile-store.js");
|
|
1013
1013
|
const profileResult = listProfiles(ctx.phrenPath);
|
|
1014
1014
|
if (!profileResult.ok) {
|
|
1015
1015
|
return jsonOk(res, { ok: false, error: profileResult.error, profiles: [] });
|
|
@@ -1027,7 +1027,6 @@ function handlePostProfile(req, res, url, ctx) {
|
|
|
1027
1027
|
if (!profileName)
|
|
1028
1028
|
return jsonErr(res, "Profile name required", 400);
|
|
1029
1029
|
try {
|
|
1030
|
-
const { setMachineProfile, getDefaultMachineAlias } = require("../profile-store.js");
|
|
1031
1030
|
const machineAlias = getDefaultMachineAlias();
|
|
1032
1031
|
const result = setMachineProfile(ctx.phrenPath, machineAlias, profileName);
|
|
1033
1032
|
if (!result.ok)
|
|
@@ -1082,7 +1081,6 @@ function handlePostSettingsProjectOverrides(req, res, url, ctx) {
|
|
|
1082
1081
|
if (globalUpdate) {
|
|
1083
1082
|
try {
|
|
1084
1083
|
if (NUMERIC_RETENTION_FIELDS.includes(field)) {
|
|
1085
|
-
const { updateRetentionPolicy } = require("../governance/policy.js");
|
|
1086
1084
|
let updateData = {};
|
|
1087
1085
|
if (!clearField) {
|
|
1088
1086
|
const num = parseFloat(value);
|
|
@@ -1096,7 +1094,6 @@ function handlePostSettingsProjectOverrides(req, res, url, ctx) {
|
|
|
1096
1094
|
return jsonOk(res, { ok: true, retentionPolicy: result.data });
|
|
1097
1095
|
}
|
|
1098
1096
|
else if (field.startsWith("decay.")) {
|
|
1099
|
-
const { updateRetentionPolicy } = require("../governance/policy.js");
|
|
1100
1097
|
const point = field.slice("decay.".length);
|
|
1101
1098
|
let updateData = {};
|
|
1102
1099
|
if (!clearField) {
|
|
@@ -1118,7 +1115,6 @@ function handlePostSettingsProjectOverrides(req, res, url, ctx) {
|
|
|
1118
1115
|
return jsonOk(res, { ok: true, workflowPolicy: result.data });
|
|
1119
1116
|
}
|
|
1120
1117
|
else if (NUMERIC_WORKFLOW_FIELDS.includes(field)) {
|
|
1121
|
-
const { updateWorkflowPolicy } = require("../governance/policy.js");
|
|
1122
1118
|
let updateData = {};
|
|
1123
1119
|
if (!clearField) {
|
|
1124
1120
|
const num = parseFloat(value);
|
package/dist/utils-fts.js
CHANGED
|
@@ -3,7 +3,8 @@ import * as path from "path";
|
|
|
3
3
|
import * as yaml from "js-yaml";
|
|
4
4
|
import { fileURLToPath } from "url";
|
|
5
5
|
import { findPhrenPath } from "./phren-paths.js";
|
|
6
|
-
import { isValidProjectName
|
|
6
|
+
import { isValidProjectName } from "./utils-paths.js";
|
|
7
|
+
import { storeAwareProjectPath } from "./store-routing.js";
|
|
7
8
|
// Lazy import of logDebug to break circular dependency:
|
|
8
9
|
// utils.ts -> phren-paths.ts -> logger.ts -> phren-paths.ts -> utils.ts
|
|
9
10
|
let _logDebug;
|
|
@@ -184,7 +185,7 @@ function parseLearnedSynonymsJson(filePath) {
|
|
|
184
185
|
export function learnedSynonymsPath(phrenPath, project) {
|
|
185
186
|
if (!isValidProjectName(project))
|
|
186
187
|
return null;
|
|
187
|
-
return
|
|
188
|
+
return storeAwareProjectPath(phrenPath, project, LEARNED_SYNONYMS_FILE);
|
|
188
189
|
}
|
|
189
190
|
export function loadLearnedSynonyms(project, phrenPath) {
|
|
190
191
|
if (!project || !isValidProjectName(project))
|
package/dist/utils-paths.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
1
|
export declare function isValidProjectName(name: string): boolean;
|
|
2
2
|
export declare function safeProjectPath(base: string, ...segments: string[]): string | null;
|
|
3
|
+
export declare const QUEUE_FILENAME = "review.md";
|
|
3
4
|
export declare function queueFilePath(phrenPath: string, project: string): string;
|
package/dist/utils-paths.js
CHANGED
|
@@ -48,7 +48,7 @@ export function safeProjectPath(base, ...segments) {
|
|
|
48
48
|
}
|
|
49
49
|
return resolved;
|
|
50
50
|
}
|
|
51
|
-
const QUEUE_FILENAME = "review.md";
|
|
51
|
+
export const QUEUE_FILENAME = "review.md";
|
|
52
52
|
export function queueFilePath(phrenPath, project) {
|
|
53
53
|
if (!isValidProjectName(project)) {
|
|
54
54
|
throw new Error(`Invalid project name: ${project}`);
|
package/dist/utils.d.ts
CHANGED
|
@@ -1,3 +1,3 @@
|
|
|
1
1
|
export { runGitOrThrow, runGit, normalizeExecCommand, resolveExecCommand, errorMessage, isFeatureEnabled, clampInt, getOptionValue, getPositionalArgs, } from "./utils-helpers.js";
|
|
2
|
-
export { isValidProjectName, safeProjectPath, queueFilePath, } from "./utils-paths.js";
|
|
2
|
+
export { isValidProjectName, safeProjectPath, queueFilePath, QUEUE_FILENAME, } from "./utils-paths.js";
|
|
3
3
|
export { STOP_WORDS, extractKeywordEntries, extractKeywords, learnedSynonymsPath, loadLearnedSynonyms, loadSynonymMap, learnSynonym, removeLearnedSynonym, sanitizeFts5Query, buildRobustFtsQuery, buildRelaxedFtsQuery, buildFtsQueryVariants, } from "./utils-fts.js";
|
package/dist/utils.js
CHANGED
|
@@ -2,5 +2,5 @@
|
|
|
2
2
|
// helpers, argv parsing, exec helpers), utils-paths.ts (path validation),
|
|
3
3
|
// utils-fts.ts (FTS5 query building, synonym/keyword extraction).
|
|
4
4
|
export { runGitOrThrow, runGit, normalizeExecCommand, resolveExecCommand, errorMessage, isFeatureEnabled, clampInt, getOptionValue, getPositionalArgs, } from "./utils-helpers.js";
|
|
5
|
-
export { isValidProjectName, safeProjectPath, queueFilePath, } from "./utils-paths.js";
|
|
5
|
+
export { isValidProjectName, safeProjectPath, queueFilePath, QUEUE_FILENAME, } from "./utils-paths.js";
|
|
6
6
|
export { STOP_WORDS, extractKeywordEntries, extractKeywords, learnedSynonymsPath, loadLearnedSynonyms, loadSynonymMap, learnSynonym, removeLearnedSynonym, sanitizeFts5Query, buildRobustFtsQuery, buildRelaxedFtsQuery, buildFtsQueryVariants, } from "./utils-fts.js";
|
package/package.json
CHANGED
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@phren/cli",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "Knowledge layer for AI agents
|
|
3
|
+
"version": "0.1.44",
|
|
4
|
+
"description": "Knowledge layer for AI agents \u2014 CLI, MCP server, and data layer",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
7
|
"phren": "dist/index.js"
|
|
8
8
|
},
|
|
9
|
+
"main": "./dist/index.js",
|
|
10
|
+
"types": "./dist/index.d.ts",
|
|
9
11
|
"exports": {
|
|
10
12
|
".": {
|
|
11
13
|
"types": "./dist/index.d.ts",
|
|
@@ -27,6 +29,26 @@
|
|
|
27
29
|
"types": "./dist/shared/retrieval.d.ts",
|
|
28
30
|
"default": "./dist/shared/retrieval.js"
|
|
29
31
|
},
|
|
32
|
+
"./shared/content": {
|
|
33
|
+
"types": "./dist/shared/content.d.ts",
|
|
34
|
+
"default": "./dist/shared/content.js"
|
|
35
|
+
},
|
|
36
|
+
"./shared/governance": {
|
|
37
|
+
"types": "./dist/shared/governance.d.ts",
|
|
38
|
+
"default": "./dist/shared/governance.js"
|
|
39
|
+
},
|
|
40
|
+
"./skill/registry": {
|
|
41
|
+
"types": "./dist/skill/registry.d.ts",
|
|
42
|
+
"default": "./dist/skill/registry.js"
|
|
43
|
+
},
|
|
44
|
+
"./cli/extract": {
|
|
45
|
+
"types": "./dist/cli/extract.d.ts",
|
|
46
|
+
"default": "./dist/cli/extract.js"
|
|
47
|
+
},
|
|
48
|
+
"./store-routing": {
|
|
49
|
+
"types": "./dist/store-routing.d.ts",
|
|
50
|
+
"default": "./dist/store-routing.js"
|
|
51
|
+
},
|
|
30
52
|
"./data/access": {
|
|
31
53
|
"types": "./dist/data/access.d.ts",
|
|
32
54
|
"default": "./dist/data/access.js"
|
|
@@ -82,14 +104,12 @@
|
|
|
82
104
|
"preuninstall": "node scripts/preuninstall.mjs"
|
|
83
105
|
},
|
|
84
106
|
"dependencies": {
|
|
85
|
-
"3d-force-graph": "^1.80.0",
|
|
86
107
|
"@modelcontextprotocol/sdk": "^1.29.0",
|
|
87
108
|
"chalk": "^5.6.2",
|
|
88
109
|
"glob": "^13.0.6",
|
|
89
110
|
"inquirer": "^14.0.2",
|
|
90
111
|
"js-yaml": "^4.2.0",
|
|
91
112
|
"sql.js-fts5": "^1.4.0",
|
|
92
|
-
"three": "^0.184.0",
|
|
93
113
|
"zod": "^4.4.3"
|
|
94
114
|
},
|
|
95
115
|
"engines": {
|
|
@@ -108,5 +128,12 @@
|
|
|
108
128
|
"type": "git",
|
|
109
129
|
"url": "git+https://github.com/alaarab/phren.git",
|
|
110
130
|
"directory": "packages/cli"
|
|
131
|
+
},
|
|
132
|
+
"devDependencies": {
|
|
133
|
+
"3d-force-graph": "^1.80.0",
|
|
134
|
+
"three": "^0.184.0"
|
|
135
|
+
},
|
|
136
|
+
"publishConfig": {
|
|
137
|
+
"access": "public"
|
|
111
138
|
}
|
|
112
139
|
}
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: phren-consolidate
|
|
3
|
+
description: Find patterns across project findings and surface insights that apply everywhere.
|
|
4
|
+
dependencies:
|
|
5
|
+
- git
|
|
6
|
+
---
|
|
7
|
+
# phren-consolidate - Cross-project synthesis
|
|
8
|
+
|
|
9
|
+
> Find patterns across project findings and surface insights that apply everywhere.
|
|
10
|
+
|
|
11
|
+
Read every project's FINDINGS.md, find patterns that show up across multiple projects, and write them to a shared global findings file.
|
|
12
|
+
|
|
13
|
+
The point: something you learned on one project probably applies elsewhere. This surfaces those connections.
|
|
14
|
+
|
|
15
|
+
## Prerequisites
|
|
16
|
+
|
|
17
|
+
This skill needs at least two projects with FINDINGS.md files to be useful. If you haven't captured any findings yet, use `add_finding()` during a session first.
|
|
18
|
+
|
|
19
|
+
**Works with or without profiles.** If profiles are set up, it scans projects in the active profile. If not, it scans all project directories in the phren repo.
|
|
20
|
+
|
|
21
|
+
## When to run
|
|
22
|
+
|
|
23
|
+
- Monthly, or when the user asks
|
|
24
|
+
- After a burst of work across multiple projects
|
|
25
|
+
- When starting a new project (to seed it with relevant cross-cutting knowledge)
|
|
26
|
+
|
|
27
|
+
## What to do
|
|
28
|
+
|
|
29
|
+
### 1. Find the phren directory
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
|
|
33
|
+
ls "$PHREN_DIR" 2>/dev/null
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
If it doesn't exist, tell the user:
|
|
37
|
+
> "No phren directory found at ~/.phren. This skill needs a phren repo with project findings. Run `phren-init` to set one up, or set PHREN_DIR if yours is elsewhere."
|
|
38
|
+
|
|
39
|
+
### 2. Gather ALL findings
|
|
40
|
+
|
|
41
|
+
Try the profile-aware path first, fall back to scanning all directories:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
MACHINE=$(cat ~/.phren/.machine-id 2>/dev/null || hostname)
|
|
45
|
+
# look up profile in machines.yaml to get the project list
|
|
46
|
+
|
|
47
|
+
# fallback: scan all project directories
|
|
48
|
+
FINDINGS_FILES=()
|
|
49
|
+
for dir in "$PHREN_DIR"/*/; do
|
|
50
|
+
if [ -f "$dir/FINDINGS.md" ]; then
|
|
51
|
+
PROJECT_NAME=$(basename "$dir")
|
|
52
|
+
FINDINGS_FILES+=("$PROJECT_NAME:$dir/FINDINGS.md")
|
|
53
|
+
fi
|
|
54
|
+
done
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Read **every** FINDINGS.md file found. Don't sample or skip any. For each file, track which project it came from.
|
|
58
|
+
|
|
59
|
+
If no FINDINGS.md files exist anywhere, tell the user:
|
|
60
|
+
> "No FINDINGS.md files found in any project. Use `add_finding()` during a work session to start capturing findings."
|
|
61
|
+
|
|
62
|
+
If only one project has a FINDINGS.md, tell the user:
|
|
63
|
+
> "Only found findings for <project>. Need at least two projects to find cross-cutting patterns. Use `add_finding()` in other projects first."
|
|
64
|
+
|
|
65
|
+
### 3. Find cross-cutting patterns
|
|
66
|
+
|
|
67
|
+
Compare findings across all projects. A pattern counts as cross-cutting when the **same insight, technique, or pitfall** appears in 2+ projects. Don't just look for keyword overlap; look for conceptual overlap.
|
|
68
|
+
|
|
69
|
+
Be specific. Not "testing is important" but "mocking at service boundaries instead of HTTP layer caught integration bugs in both my-app and backend."
|
|
70
|
+
|
|
71
|
+
Common categories (use only the ones that have actual matches):
|
|
72
|
+
|
|
73
|
+
- **Build and tooling**: cache issues, config pitfalls, CI patterns
|
|
74
|
+
- **Testing**: mocking strategies, fixture patterns, what to test vs skip
|
|
75
|
+
- **TypeScript/JS**: type tricks, async pitfalls, framework quirks
|
|
76
|
+
- **State management**: reactivity pitfalls, update ordering, stale closures
|
|
77
|
+
- **API patterns**: error handling, retry logic, auth flows
|
|
78
|
+
- **Performance**: what actually mattered vs premature optimization
|
|
79
|
+
- **Git and workflow**: branching patterns, commit conventions, release steps
|
|
80
|
+
- **Dependencies**: version conflicts, peer dep issues, lock file handling
|
|
81
|
+
|
|
82
|
+
Don't force categories. If only one project mentions something, it stays project-specific. If a pattern genuinely spans projects, include it even if it doesn't fit a neat category.
|
|
83
|
+
|
|
84
|
+
### 4. Check existing global findings
|
|
85
|
+
|
|
86
|
+
Before writing, read `$PHREN_DIR/global/FINDINGS.md` if it exists. Don't duplicate entries that are already there. Update existing entries if there's new evidence or additional projects that confirm the pattern.
|
|
87
|
+
|
|
88
|
+
### 5. Write global findings
|
|
89
|
+
|
|
90
|
+
File: `$PHREN_DIR/global/FINDINGS.md`
|
|
91
|
+
|
|
92
|
+
```markdown
|
|
93
|
+
# Cross-project findings
|
|
94
|
+
|
|
95
|
+
Last consolidated: <date>
|
|
96
|
+
Sources: <list of project names scanned>
|
|
97
|
+
|
|
98
|
+
## Build and tooling
|
|
99
|
+
- Clear dist/ after any tsconfig change, the build cache doesn't invalidate (my-app, backend)
|
|
100
|
+
- Lock file conflicts: delete and regenerate, don't try to merge (my-app, frontend)
|
|
101
|
+
|
|
102
|
+
## Testing
|
|
103
|
+
- Mock at the service boundary, not the HTTP layer (backend, frontend)
|
|
104
|
+
- Session-scoped fixtures cause flaky parallel tests (backend, my-app)
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Rules for each entry:
|
|
108
|
+
- Include which projects it came from in parentheses
|
|
109
|
+
- Be specific enough that someone could act on it without reading the original findings
|
|
110
|
+
- If two projects describe the same thing differently, synthesize into one clear statement
|
|
111
|
+
- Keep entries to 1-2 lines max
|
|
112
|
+
|
|
113
|
+
### 6. Report
|
|
114
|
+
|
|
115
|
+
```
|
|
116
|
+
phren-consolidate
|
|
117
|
+
|
|
118
|
+
Scanned: my-app (12 findings), backend (8 findings), frontend (5 findings)
|
|
119
|
+
|
|
120
|
+
Found 6 cross-cutting patterns:
|
|
121
|
+
Build: 2 patterns (cache invalidation, lock file handling)
|
|
122
|
+
Testing: 2 patterns (mock boundaries, fixture scoping)
|
|
123
|
+
TypeScript: 2 patterns (strict nulls, path aliases)
|
|
124
|
+
|
|
125
|
+
New patterns added: 4
|
|
126
|
+
Existing patterns updated: 2 (added new project evidence)
|
|
127
|
+
Skipped: 0 (already captured)
|
|
128
|
+
|
|
129
|
+
Updated: $PHREN_DIR/global/FINDINGS.md
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### 7. Commit (if git repo)
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
cd "$PHREN_DIR"
|
|
136
|
+
git add global/FINDINGS.md
|
|
137
|
+
git commit -m "update global findings"
|
|
138
|
+
git push # only if remote exists
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
## What not to do
|
|
142
|
+
|
|
143
|
+
- Don't include findings that only apply to one project. Those stay in the project's own file.
|
|
144
|
+
- Don't water down specifics to make them "general." If it's about Angular signals specifically, say so.
|
|
145
|
+
- Don't duplicate what's already in global findings. Update existing entries if there's new evidence.
|
|
146
|
+
- Don't create a wall of text. Keep it scannable. Bullet points, grouped by theme.
|
|
147
|
+
- Don't invent patterns. If two findings use the same word but describe different problems, they're not a pattern.
|
|
148
|
+
|
|
149
|
+
## Related skills
|
|
150
|
+
|
|
151
|
+
- `add_finding()`: capture findings during a session via MCP
|
|
152
|
+
- `phren-sync`: sync the consolidated findings to other machines
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: phren-discover
|
|
3
|
+
description: Audit your phren repo and tell you exactly what needs attention.
|
|
4
|
+
dependencies:
|
|
5
|
+
- git
|
|
6
|
+
- gh
|
|
7
|
+
---
|
|
8
|
+
# phren-discover - Phren health check
|
|
9
|
+
|
|
10
|
+
> Audit your phren repo and tell you exactly what needs attention.
|
|
11
|
+
|
|
12
|
+
Scans your phren directory for missing files, stale content, skill gaps, and stuck task items. Outputs a concrete, prioritized action list.
|
|
13
|
+
|
|
14
|
+
**Works standalone.** Just needs a phren directory.
|
|
15
|
+
|
|
16
|
+
## When to run
|
|
17
|
+
|
|
18
|
+
- Weekly or monthly maintenance
|
|
19
|
+
- When you feel like things are getting messy
|
|
20
|
+
- Before starting a new project (to see what you've been neglecting)
|
|
21
|
+
- When the user asks "what should I work on"
|
|
22
|
+
|
|
23
|
+
## What to do
|
|
24
|
+
|
|
25
|
+
### 1. Find the phren directory
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
|
|
29
|
+
ls "$PHREN_DIR" 2>/dev/null
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
If it doesn't exist:
|
|
33
|
+
> "No phren directory found at ~/.phren. Run `phren-init` to set one up."
|
|
34
|
+
|
|
35
|
+
### 2. Scan all projects
|
|
36
|
+
|
|
37
|
+
For each project directory in `$PHREN_DIR/*/` (skip `global/`, `profiles/`):
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
for dir in "$PHREN_DIR"/*/; do
|
|
41
|
+
PROJECT=$(basename "$dir")
|
|
42
|
+
[ "$PROJECT" = "global" ] || [ "$PROJECT" = "profiles" ] && continue
|
|
43
|
+
|
|
44
|
+
[ -f "$dir/CLAUDE.md" ] && echo "$PROJECT: has CLAUDE.md" || echo "$PROJECT: MISSING CLAUDE.md"
|
|
45
|
+
[ -f "$dir/summary.md" ] && echo "$PROJECT: has summary.md" || echo "$PROJECT: MISSING summary.md"
|
|
46
|
+
[ -f "$dir/FINDINGS.md" ] && echo "$PROJECT: has FINDINGS.md" || echo "$PROJECT: MISSING FINDINGS.md"
|
|
47
|
+
[ -f "$dir/tasks.md" ] && echo "$PROJECT: has tasks.md" || echo "$PROJECT: MISSING tasks.md"
|
|
48
|
+
done
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### 3. Check staleness
|
|
52
|
+
|
|
53
|
+
For projects that are in a git-tracked phren, check when files were last modified:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
cd "$PHREN_DIR"
|
|
57
|
+
for dir in */; do
|
|
58
|
+
PROJECT=$(basename "$dir")
|
|
59
|
+
[ "$PROJECT" = "global" ] || [ "$PROJECT" = "profiles" ] && continue
|
|
60
|
+
|
|
61
|
+
if [ -f "$dir/FINDINGS.md" ]; then
|
|
62
|
+
LAST_MODIFIED=$(git log -1 --format="%cr" -- "$dir/FINDINGS.md" 2>/dev/null || stat -c %Y "$dir/FINDINGS.md" 2>/dev/null || stat -f %m "$dir/FINDINGS.md" 2>/dev/null)
|
|
63
|
+
echo "$PROJECT/FINDINGS.md: last updated $LAST_MODIFIED"
|
|
64
|
+
fi
|
|
65
|
+
|
|
66
|
+
if [ -f "$dir/CLAUDE.md" ]; then
|
|
67
|
+
LAST_MODIFIED=$(git log -1 --format="%cr" -- "$dir/CLAUDE.md" 2>/dev/null || stat -c %Y "$dir/CLAUDE.md" 2>/dev/null || stat -f %m "$dir/CLAUDE.md" 2>/dev/null)
|
|
68
|
+
echo "$PROJECT/CLAUDE.md: last updated $LAST_MODIFIED"
|
|
69
|
+
fi
|
|
70
|
+
done
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Flag anything not updated in 30+ days as stale.
|
|
74
|
+
|
|
75
|
+
### 4. Detect skill gaps
|
|
76
|
+
|
|
77
|
+
Look at patterns in tasks.md files and FINDINGS.md files across projects. A skill gap is when:
|
|
78
|
+
- Multiple projects repeat the same manual process (e.g., "remember to update the changelog," which should be a skill)
|
|
79
|
+
- A FINDINGS.md entry says "next time, do X first," which is a skill waiting to happen
|
|
80
|
+
- A task item keeps getting deferred, and might need a skill to make it easier
|
|
81
|
+
|
|
82
|
+
Also check global/skills/ to see what skills exist, and whether any project's workflow isn't covered.
|
|
83
|
+
|
|
84
|
+
### 5. Check task health
|
|
85
|
+
|
|
86
|
+
For each project with a tasks.md:
|
|
87
|
+
- Count total items, completed items, items with no recent progress
|
|
88
|
+
- Flag tasks where nothing has been completed recently
|
|
89
|
+
- Flag tasks with items older than 60 days that haven't moved
|
|
90
|
+
|
|
91
|
+
### 6. Scaffold missing summary.md files
|
|
92
|
+
|
|
93
|
+
For each project with a missing summary.md, output the template and offer to create it:
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
Project: myapp
|
|
97
|
+
MISSING: summary.md
|
|
98
|
+
|
|
99
|
+
Template:
|
|
100
|
+
```
|
|
101
|
+
# myapp
|
|
102
|
+
|
|
103
|
+
What:
|
|
104
|
+
Stack:
|
|
105
|
+
Status: active
|
|
106
|
+
Run:
|
|
107
|
+
Watch out:
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Want me to fill this in for myapp?
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
If yes, gather the 5 fields from the user and write the file to `$PHREN_DIR/myapp/summary.md`.
|
|
114
|
+
|
|
115
|
+
### 7. Output the report
|
|
116
|
+
|
|
117
|
+
```
|
|
118
|
+
phren-discover
|
|
119
|
+
|
|
120
|
+
## Section 1: Missing files
|
|
121
|
+
|
|
122
|
+
Projects without core files:
|
|
123
|
+
|
|
124
|
+
| Project | CLAUDE.md | summary.md | FINDINGS.md | tasks.md |
|
|
125
|
+
|---------|-----------|------------|--------------|------------|
|
|
126
|
+
| myapp | ok | MISSING | MISSING | ok |
|
|
127
|
+
| api | ok | ok | ok | MISSING |
|
|
128
|
+
|
|
129
|
+
## Section 2: Stale content
|
|
130
|
+
|
|
131
|
+
Files not updated in 30+ days:
|
|
132
|
+
- my-app/FINDINGS.md: last updated 45 days ago
|
|
133
|
+
- frontend/CLAUDE.md: last updated 62 days ago
|
|
134
|
+
|
|
135
|
+
## Section 3: Skill gaps
|
|
136
|
+
|
|
137
|
+
Things you do repeatedly that could be skills:
|
|
138
|
+
- "Update changelog before release" appears in 3 project tasks. Consider a `/changelog` skill.
|
|
139
|
+
- my-app FINDINGS.md mentions "always run parity check" 4 times. Already have `/parity`, but it's not in the workflow skill.
|
|
140
|
+
|
|
141
|
+
## Section 4: Task health
|
|
142
|
+
|
|
143
|
+
- my-app: 12 items (3 completed, 2 stale > 60 days)
|
|
144
|
+
- backend: 5 items (0 completed, all stale)
|
|
145
|
+
- frontend: 8 items (6 completed, healthy)
|
|
146
|
+
|
|
147
|
+
Stuck items:
|
|
148
|
+
- backend#2: "Add rate limiting" (added 90 days ago, no progress)
|
|
149
|
+
- my-app#7: "Improve query performance" (added 75 days ago, no progress)
|
|
150
|
+
|
|
151
|
+
## Top 3 things to work on next
|
|
152
|
+
|
|
153
|
+
1. **Add FINDINGS.md to myapp.** You've been working on it actively but capturing nothing. Use `add_finding()` during your next session.
|
|
154
|
+
2. **Unstick api-server task.** 5 items, 0 completed. Either work them or trim them. Stale tasks are worse than no task.
|
|
155
|
+
3. **Create a `/changelog` skill.** You're doing it manually in 3 projects. 15 minutes to write the skill saves hours over time.
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
The "Top 3" section is the most important part. Make these:
|
|
159
|
+
- Concrete (not "improve documentation" but "add FINDINGS.md to myapp")
|
|
160
|
+
- Prioritized (highest impact first)
|
|
161
|
+
- Actionable (someone could start right now)
|
|
162
|
+
|
|
163
|
+
## What not to do
|
|
164
|
+
|
|
165
|
+
- Don't flag missing files in projects that are archived or inactive
|
|
166
|
+
- Don't recommend creating files just for completeness; only flag what would actually help
|
|
167
|
+
- Don't be vague in the Top 3. Every item should be a clear next action.
|
|
168
|
+
- Don't pad the report with things that are fine. Focus on what needs attention.
|
|
169
|
+
|
|
170
|
+
## Related skills
|
|
171
|
+
|
|
172
|
+
- `phren-init`: scaffold missing files for a project
|
|
173
|
+
- `add_finding()`: capture findings via MCP (fixes "missing FINDINGS.md")
|
|
174
|
+
- `phren-consolidate`: synthesize cross-project patterns
|
|
175
|
+
- `/tasks`: work on stuck task items
|