@phren/cli 0.1.40 → 0.1.41
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/auth/profiles.js +59 -5
- package/dist/cli/actions.js +11 -3
- package/dist/cli/config-access.js +8 -1
- package/dist/cli/extract.d.ts +27 -1
- package/dist/cli/extract.js +243 -9
- package/dist/cli/govern.js +6 -87
- package/dist/cli/hooks-context.d.ts +1 -1
- package/dist/cli/hooks-context.js +1 -1
- package/dist/cli/namespaces-review.js +14 -1
- package/dist/cli/session-git.d.ts +18 -0
- package/dist/cli/session-git.js +47 -0
- package/dist/cli/session-start.js +2 -2
- package/dist/cli/session-stop.d.ts +11 -0
- package/dist/cli/session-stop.js +141 -33
- package/dist/cli/session-tool-hook.js +17 -5
- package/dist/cli-registry.d.ts +1 -1
- package/dist/cli-registry.js +1 -0
- package/dist/content/dedup.d.ts +1 -4
- package/dist/content/dedup.js +7 -63
- package/dist/content/learning.d.ts +20 -2
- package/dist/content/learning.js +21 -3
- package/dist/content/quality.d.ts +23 -0
- package/dist/content/quality.js +123 -0
- package/dist/content/secrets.d.ts +52 -0
- package/dist/content/secrets.js +193 -0
- package/dist/data/access.d.ts +56 -2
- package/dist/data/access.js +246 -24
- package/dist/entrypoint.js +5 -1
- package/dist/finding/impact.js +170 -43
- package/dist/finding/lifecycle.d.ts +19 -2
- package/dist/finding/lifecycle.js +15 -3
- package/dist/git-worktree.d.ts +19 -0
- package/dist/git-worktree.js +117 -0
- package/dist/governance/policy.d.ts +84 -4
- package/dist/governance/policy.js +209 -14
- package/dist/governance/rbac.d.ts +8 -0
- package/dist/governance/rbac.js +26 -0
- package/dist/hooks.d.ts +20 -0
- package/dist/hooks.js +113 -3
- package/dist/index.js +5 -1
- package/dist/init/guard-globals.d.ts +20 -0
- package/dist/init/guard-globals.js +72 -6
- package/dist/init/init-configure.js +6 -6
- package/dist/init/init.js +10 -6
- package/dist/init/setup.d.ts +4 -3
- package/dist/init/setup.js +120 -16
- package/dist/init/store-gitignore.d.ts +29 -0
- package/dist/init/store-gitignore.js +48 -0
- package/dist/link/doctor.js +86 -20
- package/dist/phren-core.d.ts +35 -8
- package/dist/phren-core.js +35 -8
- package/dist/phren-paths.d.ts +90 -1
- package/dist/phren-paths.js +150 -5
- package/dist/proactivity.js +1 -1
- package/dist/shared/embedding-cache.d.ts +16 -0
- package/dist/shared/embedding-cache.js +24 -0
- package/dist/shared/fragment-graph.js +10 -0
- package/dist/shared/index.d.ts +6 -0
- package/dist/shared/index.js +523 -138
- package/dist/shared/ollama.d.ts +14 -2
- package/dist/shared/ollama.js +84 -5
- package/dist/shared/retrieval.d.ts +22 -1
- package/dist/shared/retrieval.js +30 -1
- package/dist/shared/search-fallback.js +15 -3
- package/dist/shared/vector-index.d.ts +20 -1
- package/dist/shared/vector-index.js +18 -4
- package/dist/shared.d.ts +1 -1
- package/dist/shared.js +1 -1
- package/dist/status.js +18 -1
- package/dist/store-registry.d.ts +22 -0
- package/dist/store-registry.js +36 -3
- package/dist/task/lifecycle.js +31 -0
- package/dist/tools/config.js +16 -7
- package/dist/tools/data.js +1 -1
- package/dist/tools/extract.js +2 -2
- package/dist/tools/finding.js +14 -3
- package/dist/tools/graph.js +9 -1
- package/dist/tools/memory.js +1 -1
- package/dist/tools/notes.js +3 -3
- package/dist/tools/ops.js +19 -18
- package/dist/tools/search.js +2 -2
- package/dist/tools/session.js +2 -2
- package/dist/tools/tasks.js +2 -2
- package/dist/tools/types.d.ts +32 -2
- package/dist/tools/types.js +41 -8
- package/dist/ui/scripts.js +2 -2
- package/dist/ui/server.js +5 -0
- package/package.json +1 -1
- package/dist/cli-hooks-git.d.ts +0 -50
- package/dist/cli-hooks-git.js +0 -288
- package/starter/my-api/.claude/skills/README.md +0 -7
- package/starter/my-api/CLAUDE.md +0 -33
- package/starter/my-api/FINDINGS.md +0 -9
- package/starter/my-api/summary.md +0 -7
- package/starter/my-api/tasks.md +0 -7
- package/starter/my-first-project/.claude/skills/README.md +0 -7
- package/starter/my-first-project/CLAUDE.md +0 -49
- package/starter/my-first-project/FINDINGS.md +0 -24
- package/starter/my-first-project/summary.md +0 -11
- package/starter/my-first-project/tasks.md +0 -25
- package/starter/my-frontend/.claude/skills/README.md +0 -7
- package/starter/my-frontend/CLAUDE.md +0 -33
- package/starter/my-frontend/FINDINGS.md +0 -9
- package/starter/my-frontend/summary.md +0 -7
- package/starter/my-frontend/tasks.md +0 -7
package/dist/cli-hooks-git.js
DELETED
|
@@ -1,288 +0,0 @@
|
|
|
1
|
-
import { debugLog, EXEC_TIMEOUT_MS, withFileLock, recordFeedback, getQualityMultiplier, errorMessage, } from "./cli/hooks-context.js";
|
|
2
|
-
import { sessionMetricsFile, } from "./shared.js";
|
|
3
|
-
import { autoMergeConflicts, mergeTask, mergeFindings, } from "./shared/content.js";
|
|
4
|
-
import { runGit } from "./utils.js";
|
|
5
|
-
import { isTaskFileName } from "./data/tasks.js";
|
|
6
|
-
import * as fs from "fs";
|
|
7
|
-
import * as path from "path";
|
|
8
|
-
import { execFileSync } from "child_process";
|
|
9
|
-
import { fileURLToPath } from "url";
|
|
10
|
-
export function getGitContext(cwd) {
|
|
11
|
-
if (!cwd)
|
|
12
|
-
return null;
|
|
13
|
-
const git = (args) => runGit(cwd, args, EXEC_TIMEOUT_MS, debugLog);
|
|
14
|
-
const branch = git(["rev-parse", "--abbrev-ref", "HEAD"]);
|
|
15
|
-
if (!branch)
|
|
16
|
-
return null;
|
|
17
|
-
const changedFiles = new Set();
|
|
18
|
-
for (const changed of [
|
|
19
|
-
git(["diff", "--name-only"]),
|
|
20
|
-
git(["diff", "--name-only", "--cached"]),
|
|
21
|
-
]) {
|
|
22
|
-
if (!changed)
|
|
23
|
-
continue;
|
|
24
|
-
for (const line of changed.split("\n").map((s) => s.trim()).filter(Boolean)) {
|
|
25
|
-
changedFiles.add(line);
|
|
26
|
-
const basename = path.basename(line);
|
|
27
|
-
if (basename)
|
|
28
|
-
changedFiles.add(basename);
|
|
29
|
-
}
|
|
30
|
-
}
|
|
31
|
-
return { branch, changedFiles };
|
|
32
|
-
}
|
|
33
|
-
export function parseSessionMetrics(phrenPathLocal) {
|
|
34
|
-
const file = sessionMetricsFile(phrenPathLocal);
|
|
35
|
-
if (!fs.existsSync(file))
|
|
36
|
-
return {};
|
|
37
|
-
try {
|
|
38
|
-
return JSON.parse(fs.readFileSync(file, "utf8"));
|
|
39
|
-
}
|
|
40
|
-
catch (err) {
|
|
41
|
-
debugLog(`parseSessionMetrics: failed to read ${file}: ${errorMessage(err)}`);
|
|
42
|
-
return {};
|
|
43
|
-
}
|
|
44
|
-
}
|
|
45
|
-
export function writeSessionMetrics(phrenPathLocal, data) {
|
|
46
|
-
const file = sessionMetricsFile(phrenPathLocal);
|
|
47
|
-
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
48
|
-
fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
|
|
49
|
-
}
|
|
50
|
-
export function updateSessionMetrics(phrenPathLocal, updater) {
|
|
51
|
-
const file = sessionMetricsFile(phrenPathLocal);
|
|
52
|
-
withFileLock(file, () => {
|
|
53
|
-
const metrics = parseSessionMetrics(phrenPathLocal);
|
|
54
|
-
updater(metrics);
|
|
55
|
-
writeSessionMetrics(phrenPathLocal, metrics);
|
|
56
|
-
});
|
|
57
|
-
}
|
|
58
|
-
export function trackSessionMetrics(phrenPathLocal, sessionId, selected) {
|
|
59
|
-
updateSessionMetrics(phrenPathLocal, (metrics) => {
|
|
60
|
-
if (!metrics[sessionId])
|
|
61
|
-
metrics[sessionId] = { prompts: 0, keys: {}, lastChangedCount: 0, lastKeys: [] };
|
|
62
|
-
metrics[sessionId].prompts += 1;
|
|
63
|
-
const injectedKeys = [];
|
|
64
|
-
for (const injected of selected) {
|
|
65
|
-
injectedKeys.push(injected.key);
|
|
66
|
-
const key = injected.key;
|
|
67
|
-
const seen = metrics[sessionId].keys[key] || 0;
|
|
68
|
-
metrics[sessionId].keys[key] = seen + 1;
|
|
69
|
-
if (seen >= 1)
|
|
70
|
-
recordFeedback(phrenPathLocal, key, "reprompt");
|
|
71
|
-
}
|
|
72
|
-
const relevantCount = selected.filter((s) => getQualityMultiplier(phrenPathLocal, s.key) > 0.5).length;
|
|
73
|
-
const prevRelevant = metrics[sessionId].lastChangedCount || 0;
|
|
74
|
-
const prevKeys = metrics[sessionId].lastKeys || [];
|
|
75
|
-
if (relevantCount > prevRelevant) {
|
|
76
|
-
for (const prevKey of prevKeys) {
|
|
77
|
-
recordFeedback(phrenPathLocal, prevKey, "helpful");
|
|
78
|
-
}
|
|
79
|
-
}
|
|
80
|
-
metrics[sessionId].lastChangedCount = relevantCount;
|
|
81
|
-
metrics[sessionId].lastKeys = injectedKeys;
|
|
82
|
-
metrics[sessionId].lastSeen = new Date().toISOString();
|
|
83
|
-
const thirtyDaysAgo = Date.now() - 30 * 86400000;
|
|
84
|
-
for (const sid of Object.keys(metrics)) {
|
|
85
|
-
const seen = metrics[sid].lastSeen;
|
|
86
|
-
if (seen && new Date(seen).getTime() < thirtyDaysAgo) {
|
|
87
|
-
delete metrics[sid];
|
|
88
|
-
}
|
|
89
|
-
}
|
|
90
|
-
});
|
|
91
|
-
}
|
|
92
|
-
// ── Git command helpers for hooks ────────────────────────────────────────────
|
|
93
|
-
export function isTransientGitError(message) {
|
|
94
|
-
return /(timed out|connection|network|could not resolve host|rpc failed|429|502|503|504|service unavailable)/i.test(message);
|
|
95
|
-
}
|
|
96
|
-
export function shouldRetryGitCommand(args) {
|
|
97
|
-
const cmd = args[0] || "";
|
|
98
|
-
return cmd === "push" || cmd === "pull" || cmd === "fetch";
|
|
99
|
-
}
|
|
100
|
-
export async function runBestEffortGit(args, cwd) {
|
|
101
|
-
const retries = shouldRetryGitCommand(args) ? 2 : 0;
|
|
102
|
-
for (let attempt = 0; attempt <= retries; attempt++) {
|
|
103
|
-
try {
|
|
104
|
-
const output = execFileSync("git", args, {
|
|
105
|
-
cwd,
|
|
106
|
-
encoding: "utf8",
|
|
107
|
-
stdio: ["ignore", "pipe", "pipe"],
|
|
108
|
-
timeout: EXEC_TIMEOUT_MS,
|
|
109
|
-
}).trim();
|
|
110
|
-
return { ok: true, output };
|
|
111
|
-
}
|
|
112
|
-
catch (err) {
|
|
113
|
-
const message = errorMessage(err);
|
|
114
|
-
if (attempt < retries && isTransientGitError(message)) {
|
|
115
|
-
const delayMs = 500 * (attempt + 1);
|
|
116
|
-
await new Promise((resolve) => setTimeout(resolve, delayMs));
|
|
117
|
-
continue;
|
|
118
|
-
}
|
|
119
|
-
return { ok: false, error: message };
|
|
120
|
-
}
|
|
121
|
-
}
|
|
122
|
-
return { ok: false, error: "git command failed" };
|
|
123
|
-
}
|
|
124
|
-
/**
|
|
125
|
-
* Files phren is allowed to auto-stage in a team store. Anything not in this
|
|
126
|
-
* list (notably `.runtime/`, secrets, build output) is skipped on session-stop
|
|
127
|
-
* and `push_changes`.
|
|
128
|
-
*/
|
|
129
|
-
export const TEAM_STORE_PATHSPECS = [
|
|
130
|
-
"*/journal/*",
|
|
131
|
-
"*/tasks.md",
|
|
132
|
-
"*/truths.md",
|
|
133
|
-
"*/FINDINGS.md",
|
|
134
|
-
"*/FINDINGS.md.bak",
|
|
135
|
-
"*/summary.md",
|
|
136
|
-
"*/review.md",
|
|
137
|
-
"*/CLAUDE.md",
|
|
138
|
-
"*/topic-config.json",
|
|
139
|
-
"*/phren.project.yaml",
|
|
140
|
-
"*/reference/**",
|
|
141
|
-
"*/skills/**",
|
|
142
|
-
"*/notes/**",
|
|
143
|
-
".phren-team.yaml",
|
|
144
|
-
];
|
|
145
|
-
/**
|
|
146
|
-
* Stage each team pathspec individually so a single no-match (e.g. a store
|
|
147
|
-
* with no `truths.md` anywhere) doesn't abort the entire `git add` and strand
|
|
148
|
-
* every other change. Errors are swallowed by `runBestEffortGit` already.
|
|
149
|
-
*
|
|
150
|
-
* Returns the number of pathspecs that staged successfully — useful for
|
|
151
|
-
* telemetry, not gating.
|
|
152
|
-
*/
|
|
153
|
-
export async function addTeamPathspecs(cwd) {
|
|
154
|
-
let staged = 0;
|
|
155
|
-
for (const spec of TEAM_STORE_PATHSPECS) {
|
|
156
|
-
const result = await runBestEffortGit(["add", "--sparse", "--", spec], cwd);
|
|
157
|
-
if (result.ok)
|
|
158
|
-
staged++;
|
|
159
|
-
}
|
|
160
|
-
return staged;
|
|
161
|
-
}
|
|
162
|
-
export async function countUnsyncedCommits(cwd) {
|
|
163
|
-
const upstream = await runBestEffortGit(["rev-parse", "--abbrev-ref", "@{upstream}"], cwd);
|
|
164
|
-
if (!upstream.ok || !upstream.output) {
|
|
165
|
-
// No upstream tracking branch — count all local commits as unsynced
|
|
166
|
-
// so the warning at the call site fires instead of silently returning 0
|
|
167
|
-
const allCommits = await runBestEffortGit(["rev-list", "--count", "HEAD"], cwd);
|
|
168
|
-
if (!allCommits.ok || !allCommits.output)
|
|
169
|
-
return 0;
|
|
170
|
-
const parsed = Number.parseInt(allCommits.output.trim(), 10);
|
|
171
|
-
return Number.isNaN(parsed) ? 0 : parsed;
|
|
172
|
-
}
|
|
173
|
-
const ahead = await runBestEffortGit(["rev-list", "--count", `${upstream.output.trim()}..HEAD`], cwd);
|
|
174
|
-
if (!ahead.ok || !ahead.output)
|
|
175
|
-
return 0;
|
|
176
|
-
const parsed = Number.parseInt(ahead.output.trim(), 10);
|
|
177
|
-
return Number.isNaN(parsed) ? 0 : parsed;
|
|
178
|
-
}
|
|
179
|
-
export function isMergeableMarkdown(relPath) {
|
|
180
|
-
const filename = path.basename(relPath).toLowerCase();
|
|
181
|
-
return filename === "findings.md" || isTaskFileName(filename);
|
|
182
|
-
}
|
|
183
|
-
export async function snapshotLocalMergeableFiles(cwd) {
|
|
184
|
-
const upstream = await runBestEffortGit(["rev-parse", "--abbrev-ref", "@{upstream}"], cwd);
|
|
185
|
-
if (!upstream.ok || !upstream.output)
|
|
186
|
-
return new Map();
|
|
187
|
-
const changed = await runBestEffortGit(["diff", "--name-only", `${upstream.output.trim()}..HEAD`], cwd);
|
|
188
|
-
if (!changed.ok || !changed.output)
|
|
189
|
-
return new Map();
|
|
190
|
-
const snapshots = new Map();
|
|
191
|
-
for (const relPath of changed.output.split("\n").map((line) => line.trim()).filter(Boolean)) {
|
|
192
|
-
if (!isMergeableMarkdown(relPath))
|
|
193
|
-
continue;
|
|
194
|
-
const fullPath = path.join(cwd, relPath);
|
|
195
|
-
if (!fs.existsSync(fullPath))
|
|
196
|
-
continue;
|
|
197
|
-
snapshots.set(relPath, fs.readFileSync(fullPath, "utf8"));
|
|
198
|
-
}
|
|
199
|
-
return snapshots;
|
|
200
|
-
}
|
|
201
|
-
export async function reconcileMergeableFiles(cwd, snapshots) {
|
|
202
|
-
let changedAny = false;
|
|
203
|
-
for (const [relPath, localBeforePull] of snapshots.entries()) {
|
|
204
|
-
const fullPath = path.join(cwd, relPath);
|
|
205
|
-
if (!fs.existsSync(fullPath))
|
|
206
|
-
continue;
|
|
207
|
-
const current = fs.readFileSync(fullPath, "utf8");
|
|
208
|
-
const filename = path.basename(relPath).toLowerCase();
|
|
209
|
-
const merged = filename === "findings.md"
|
|
210
|
-
? mergeFindings(current, localBeforePull)
|
|
211
|
-
: mergeTask(current, localBeforePull);
|
|
212
|
-
if (merged === current)
|
|
213
|
-
continue;
|
|
214
|
-
fs.writeFileSync(fullPath, merged);
|
|
215
|
-
changedAny = true;
|
|
216
|
-
}
|
|
217
|
-
if (!changedAny)
|
|
218
|
-
return false;
|
|
219
|
-
const add = await runBestEffortGit(["add", "--", ...snapshots.keys()], cwd);
|
|
220
|
-
if (!add.ok)
|
|
221
|
-
return false;
|
|
222
|
-
const commit = await runBestEffortGit(["commit", "-m", "auto-merge markdown recovery"], cwd);
|
|
223
|
-
return commit.ok;
|
|
224
|
-
}
|
|
225
|
-
export async function recoverPushConflict(cwd) {
|
|
226
|
-
const localSnapshots = await snapshotLocalMergeableFiles(cwd);
|
|
227
|
-
const pull = await runBestEffortGit(["pull", "--rebase", "--quiet"], cwd);
|
|
228
|
-
if (pull.ok) {
|
|
229
|
-
const reconciled = await reconcileMergeableFiles(cwd, localSnapshots);
|
|
230
|
-
const retryPush = await runBestEffortGit(["push"], cwd);
|
|
231
|
-
return {
|
|
232
|
-
ok: retryPush.ok,
|
|
233
|
-
detail: retryPush.ok
|
|
234
|
-
? (reconciled ? "commit pushed after pull --rebase and markdown reconciliation" : "commit pushed after pull --rebase")
|
|
235
|
-
: (retryPush.error || "push failed after pull --rebase"),
|
|
236
|
-
pullStatus: "ok",
|
|
237
|
-
pullDetail: pull.output || "pull --rebase ok",
|
|
238
|
-
};
|
|
239
|
-
}
|
|
240
|
-
const conflicted = await runBestEffortGit(["diff", "--name-only", "--diff-filter=U"], cwd);
|
|
241
|
-
const conflictedOutput = conflicted.output?.trim() || "";
|
|
242
|
-
if (!conflicted.ok || !conflictedOutput) {
|
|
243
|
-
await runBestEffortGit(["rebase", "--abort"], cwd);
|
|
244
|
-
return {
|
|
245
|
-
ok: false,
|
|
246
|
-
detail: pull.error || "pull --rebase failed",
|
|
247
|
-
pullStatus: "error",
|
|
248
|
-
pullDetail: pull.error || "pull --rebase failed",
|
|
249
|
-
};
|
|
250
|
-
}
|
|
251
|
-
if (!autoMergeConflicts(cwd)) {
|
|
252
|
-
await runBestEffortGit(["rebase", "--abort"], cwd);
|
|
253
|
-
return {
|
|
254
|
-
ok: false,
|
|
255
|
-
detail: `rebase conflicts require manual resolution: ${conflictedOutput}`,
|
|
256
|
-
pullStatus: "error",
|
|
257
|
-
pullDetail: `rebase conflicts require manual resolution: ${conflictedOutput}`,
|
|
258
|
-
};
|
|
259
|
-
}
|
|
260
|
-
const continued = await runBestEffortGit(["-c", "core.editor=true", "rebase", "--continue"], cwd);
|
|
261
|
-
if (!continued.ok) {
|
|
262
|
-
await runBestEffortGit(["rebase", "--abort"], cwd);
|
|
263
|
-
return {
|
|
264
|
-
ok: false,
|
|
265
|
-
detail: continued.error || "rebase --continue failed",
|
|
266
|
-
pullStatus: "error",
|
|
267
|
-
pullDetail: continued.error || "rebase --continue failed",
|
|
268
|
-
};
|
|
269
|
-
}
|
|
270
|
-
const retryPush = await runBestEffortGit(["push"], cwd);
|
|
271
|
-
return {
|
|
272
|
-
ok: retryPush.ok,
|
|
273
|
-
detail: retryPush.ok ? "commit pushed after auto-merge recovery" : (retryPush.error || "push failed after auto-merge recovery"),
|
|
274
|
-
pullStatus: "ok",
|
|
275
|
-
pullDetail: "pull --rebase recovered via auto-merge",
|
|
276
|
-
};
|
|
277
|
-
}
|
|
278
|
-
export function resolveSubprocessArgs(command) {
|
|
279
|
-
// Prefer the entry script from process.argv[1] (the index.js that started this process)
|
|
280
|
-
const entry = process.argv[1];
|
|
281
|
-
if (entry && fs.existsSync(entry) && /index\.(ts|js)$/.test(entry))
|
|
282
|
-
return [entry, command];
|
|
283
|
-
// Fallback: look for index.js next to this file
|
|
284
|
-
const distEntry = path.join(path.dirname(fileURLToPath(import.meta.url)), "index.js");
|
|
285
|
-
if (fs.existsSync(distEntry))
|
|
286
|
-
return [distEntry, command];
|
|
287
|
-
return null;
|
|
288
|
-
}
|
package/starter/my-api/CLAUDE.md
DELETED
|
@@ -1,33 +0,0 @@
|
|
|
1
|
-
# CLAUDE.md
|
|
2
|
-
|
|
3
|
-
## Project overview
|
|
4
|
-
|
|
5
|
-
**Purpose**: Backend API. Replace this with a real description of what the service does.
|
|
6
|
-
**Stack**: Node.js, Express, PostgreSQL (or whatever you're using)
|
|
7
|
-
**Status**: active
|
|
8
|
-
**Version**: 0.0.0
|
|
9
|
-
|
|
10
|
-
## Commands
|
|
11
|
-
|
|
12
|
-
```bash
|
|
13
|
-
# Install: npm install
|
|
14
|
-
# Run: npm run dev
|
|
15
|
-
# Test: npm test
|
|
16
|
-
# Build: npm run build
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
## Project skills
|
|
20
|
-
|
|
21
|
-
Source skills live in the phren project `skills/` directory. Phren resolves global + project-local skills and mirrors the effective set into repo-local `.claude/skills/`.
|
|
22
|
-
|
|
23
|
-
## Architecture
|
|
24
|
-
|
|
25
|
-
<!-- How routes, middleware, and services are organized -->
|
|
26
|
-
|
|
27
|
-
## Key patterns
|
|
28
|
-
|
|
29
|
-
<!-- Naming rules, error handling patterns, things to never do -->
|
|
30
|
-
|
|
31
|
-
<!-- Tip: If this file grows past ~100 lines, split it using @import directives.
|
|
32
|
-
Example: @CLAUDE-architecture.md, @CLAUDE-commands.md, @CLAUDE-conventions.md
|
|
33
|
-
See phren README for details. -->
|
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
# my-api findings
|
|
2
|
-
|
|
3
|
-
Findings accumulated over time. Captured automatically during sessions and committed on exit.
|
|
4
|
-
|
|
5
|
-
<!-- Example entry:
|
|
6
|
-
## 2026-03-04
|
|
7
|
-
- The auth middleware runs before rate limiting: order matters in middleware stack
|
|
8
|
-
- `npm run dev` needs PORT set or it defaults to 3001, not 3000
|
|
9
|
-
-->
|
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
# my-api
|
|
2
|
-
|
|
3
|
-
**What:** REST API backend: replace with what yours actually does
|
|
4
|
-
**Stack:** Node.js, Express, PostgreSQL (or whatever you're using)
|
|
5
|
-
**Status:** active
|
|
6
|
-
**Run:** npm run dev
|
|
7
|
-
**Watch out:** .env not committed: copy .env.example and fill in secrets before first run
|
package/starter/my-api/tasks.md
DELETED
|
@@ -1,49 +0,0 @@
|
|
|
1
|
-
# CLAUDE.md
|
|
2
|
-
|
|
3
|
-
## Project overview
|
|
4
|
-
|
|
5
|
-
**Purpose**: One paragraph about what this project is and what it does
|
|
6
|
-
**Stack**: Replace with your tech stack
|
|
7
|
-
**Status**: active
|
|
8
|
-
**Version**: 0.0.0
|
|
9
|
-
|
|
10
|
-
## Commands
|
|
11
|
-
|
|
12
|
-
```bash
|
|
13
|
-
# Install:
|
|
14
|
-
# Run:
|
|
15
|
-
# Test:
|
|
16
|
-
# Build:
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
## Project skills
|
|
20
|
-
|
|
21
|
-
Source skills live in the phren project `skills/` directory. Phren resolves global + project-local skills and mirrors the effective set into repo-local `.claude/skills/`.
|
|
22
|
-
|
|
23
|
-
## Architecture
|
|
24
|
-
|
|
25
|
-
<!-- How the codebase is structured. Example:
|
|
26
|
-
|
|
27
|
-
src/
|
|
28
|
-
routes/ - Express route handlers
|
|
29
|
-
services/ - Business logic, one file per domain
|
|
30
|
-
models/ - Database models (Prisma)
|
|
31
|
-
middleware/ - Auth, rate-limiting, error handling
|
|
32
|
-
utils/ - Shared helpers
|
|
33
|
-
|
|
34
|
-
-->
|
|
35
|
-
|
|
36
|
-
## Key patterns
|
|
37
|
-
|
|
38
|
-
<!-- Project-specific patterns, naming rules, things to never do. Example:
|
|
39
|
-
|
|
40
|
-
- All API responses use `{ ok: boolean, data?, error? }` shape
|
|
41
|
-
- Service functions throw, route handlers catch and format
|
|
42
|
-
- Never import from `src/models` directly in routes, go through services
|
|
43
|
-
- Tests live next to source files as `*.test.ts`
|
|
44
|
-
|
|
45
|
-
-->
|
|
46
|
-
|
|
47
|
-
<!-- Tip: If this file grows past ~100 lines, split it using @import directives.
|
|
48
|
-
Example: @CLAUDE-architecture.md, @CLAUDE-commands.md, @CLAUDE-conventions.md
|
|
49
|
-
See phren README for details. -->
|
|
@@ -1,24 +0,0 @@
|
|
|
1
|
-
# my-first-project findings
|
|
2
|
-
|
|
3
|
-
Fragments accumulated over time. Captured automatically during sessions and committed on exit.
|
|
4
|
-
|
|
5
|
-
<!-- How findings work:
|
|
6
|
-
|
|
7
|
-
Phren captures insights as you code. When Claude discovers something non-obvious
|
|
8
|
-
(a pitfall, a pattern, a decision with context), it calls add_finding() and the
|
|
9
|
-
insight lands here. The Stop hook auto-commits after every response.
|
|
10
|
-
|
|
11
|
-
Entries are grouped by date. Old entries get confidence-decayed over time, so stale
|
|
12
|
-
findings fade from retrieval naturally. You can remove wrong entries with
|
|
13
|
-
remove_finding() or clean up bulk with `phren shell` > :find remove.
|
|
14
|
-
|
|
15
|
-
Example entries (delete these once you have real ones):
|
|
16
|
-
|
|
17
|
-
## 2026-03-06
|
|
18
|
-
|
|
19
|
-
- The auth middleware runs before rate limiting, order matters in the middleware stack
|
|
20
|
-
<!-- phren:cite {"created_at":"2026-03-06T00:00:00.000Z"} -->
|
|
21
|
-
- `npm run dev` needs PORT set or it defaults to 3001, not 3000
|
|
22
|
-
<!-- phren:cite {"created_at":"2026-03-06T00:00:00.000Z"} -->
|
|
23
|
-
|
|
24
|
-
-->
|
|
@@ -1,11 +0,0 @@
|
|
|
1
|
-
# my-first-project
|
|
2
|
-
|
|
3
|
-
**What:** Replace this with one sentence about what the project does
|
|
4
|
-
**Stack:** The key tech: language, framework, main deps
|
|
5
|
-
**Status:** active
|
|
6
|
-
**Run:** the command you use most (e.g. npm run dev)
|
|
7
|
-
**Watch out:** the one thing that will bite you if you forget it
|
|
8
|
-
|
|
9
|
-
<!-- This summary is the first thing phren shows Claude about your project.
|
|
10
|
-
Keep it short: 5 lines max. Think of it as the elevator pitch that helps
|
|
11
|
-
Claude understand what it's working on before reading any code. -->
|
|
@@ -1,25 +0,0 @@
|
|
|
1
|
-
# my-first-project tasks
|
|
2
|
-
|
|
3
|
-
## Active
|
|
4
|
-
|
|
5
|
-
### P0: Getting started
|
|
6
|
-
|
|
7
|
-
- [ ] Fill in CLAUDE.md with your project's commands, architecture, and conventions
|
|
8
|
-
- [ ] Update summary.md with a real description of your project
|
|
9
|
-
|
|
10
|
-
## Queue
|
|
11
|
-
|
|
12
|
-
### P1: Phren setup
|
|
13
|
-
|
|
14
|
-
- [ ] Push this phren repo to a private GitHub repo for backup
|
|
15
|
-
- [ ] Run `phren doctor` to verify everything is wired up
|
|
16
|
-
- [ ] Add a second project with `phren-init <name>` or `phren shell`
|
|
17
|
-
|
|
18
|
-
### P2: Nice to have
|
|
19
|
-
|
|
20
|
-
- [ ] Set up profiles for work vs personal machines in profiles/
|
|
21
|
-
- [ ] Add project-specific skills to the project `skills/` directory
|
|
22
|
-
|
|
23
|
-
## Done
|
|
24
|
-
|
|
25
|
-
- [x] Run `phren init` to set up phren
|
|
@@ -1,33 +0,0 @@
|
|
|
1
|
-
# CLAUDE.md
|
|
2
|
-
|
|
3
|
-
## Project overview
|
|
4
|
-
|
|
5
|
-
**Purpose**: Frontend app. Replace this with a real description of what it does.
|
|
6
|
-
**Stack**: React, TypeScript, Vite (or whatever you're using)
|
|
7
|
-
**Status**: active
|
|
8
|
-
**Version**: 0.0.0
|
|
9
|
-
|
|
10
|
-
## Commands
|
|
11
|
-
|
|
12
|
-
```bash
|
|
13
|
-
# Install: npm install
|
|
14
|
-
# Run: npm run dev
|
|
15
|
-
# Test: npm test
|
|
16
|
-
# Build: npm run build
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
## Project skills
|
|
20
|
-
|
|
21
|
-
Source skills live in the phren project `skills/` directory. Phren resolves global + project-local skills and mirrors the effective set into repo-local `.claude/skills/`.
|
|
22
|
-
|
|
23
|
-
## Architecture
|
|
24
|
-
|
|
25
|
-
<!-- Component structure, routing, state management approach -->
|
|
26
|
-
|
|
27
|
-
## Key patterns
|
|
28
|
-
|
|
29
|
-
<!-- Naming rules, component patterns, things to never do -->
|
|
30
|
-
|
|
31
|
-
<!-- Tip: If this file grows past ~100 lines, split it using @import directives.
|
|
32
|
-
Example: @CLAUDE-architecture.md, @CLAUDE-commands.md, @CLAUDE-conventions.md
|
|
33
|
-
See phren README for details. -->
|
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
# my-frontend findings
|
|
2
|
-
|
|
3
|
-
Findings accumulated over time. Captured automatically during sessions and committed on exit.
|
|
4
|
-
|
|
5
|
-
<!-- Example entry:
|
|
6
|
-
## 2026-03-04
|
|
7
|
-
- HMR breaks if you rename a component file without restarting the dev server
|
|
8
|
-
- The API base URL in .env.local must not have a trailing slash
|
|
9
|
-
-->
|
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
# my-frontend
|
|
2
|
-
|
|
3
|
-
**What:** Frontend app: replace with what yours actually does
|
|
4
|
-
**Stack:** React, TypeScript, Vite (or whatever you're using)
|
|
5
|
-
**Status:** active
|
|
6
|
-
**Run:** npm run dev
|
|
7
|
-
**Watch out:** API base URL set in .env.local: needs to match whatever port my-api runs on
|