@openplanr/protocol 0.10.1 → 0.10.3

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.
@@ -0,0 +1,4 @@
1
+ /** Folder at a project root that holds its OpenPlanr planning files. */
2
+ export declare const PLANNING_FOLDER: '.planr';
3
+ /** Command name that help, usage, errors and next-step hints show. */
4
+ export declare const CLI_COMMAND: 'openplanr';
package/src/names.mjs ADDED
@@ -0,0 +1,8 @@
1
+ // @ts-check
2
+ // The planning folder and command names that every package and generated copy reads.
3
+
4
+ /** @type {typeof import('./names.d.mts').PLANNING_FOLDER} */
5
+ export const PLANNING_FOLDER = '.planr';
6
+
7
+ /** @type {typeof import('./names.d.mts').CLI_COMMAND} */
8
+ export const CLI_COMMAND = 'openplanr';
@@ -0,0 +1,14 @@
1
+ export { PLANNING_FOLDER } from './names.mjs';
2
+
3
+ /** Why OpenPlanr refuses to write into a project's planning folder. */
4
+ export interface PlanningFolderConflict {
5
+ readonly code: 'E_PLANNING_FOLDER_FOREIGN';
6
+ readonly problem: string;
7
+ readonly fix: string;
8
+ readonly signs: readonly string[];
9
+ }
10
+
11
+ /** Signs that `<projectRoot>/.planr`, which lacks OpenPlanr's config.json, is a folder OpenPlanr didn't create; empty when OpenPlanr may write there. */
12
+ export declare function foreignPlanningFolderSigns(projectRoot: string): string[];
13
+ /** The refusal for writing into a planning folder OpenPlanr didn't create, or null when OpenPlanr may write there. */
14
+ export declare function planningFolderConflict(projectRoot: string): PlanningFolderConflict | null;
@@ -0,0 +1,40 @@
1
+ // @ts-check
2
+ // Recognizes a planning folder OpenPlanr didn't create, so OpenPlanr never writes into it.
3
+ import { existsSync, readdirSync, statSync } from 'node:fs';
4
+ import { join } from 'node:path';
5
+ import { CLI_COMMAND, PLANNING_FOLDER } from './names.mjs';
6
+
7
+ export { PLANNING_FOLDER };
8
+
9
+ const FOREIGN_FILES = Object.freeze(['planr.config.json', 'board.html']);
10
+ const GOAL_DIRECTORIES = Object.freeze(['tasks', 'plans']);
11
+
12
+ const isDirectory = (path) => existsSync(path) && statSync(path).isDirectory();
13
+
14
+ /** @type {typeof import('./planning-folder.d.mts').foreignPlanningFolderSigns} */
15
+ export function foreignPlanningFolderSigns(projectRoot) {
16
+ const folder = join(projectRoot, PLANNING_FOLDER);
17
+ if (!isDirectory(folder) || existsSync(join(folder, 'config.json'))) return [];
18
+ const signs = FOREIGN_FILES.filter((name) => existsSync(join(folder, name)));
19
+ for (const name of GOAL_DIRECTORIES) {
20
+ const directory = join(folder, name);
21
+ if (
22
+ isDirectory(directory) &&
23
+ readdirSync(directory).some((entry) => entry.endsWith('-goal.md'))
24
+ )
25
+ signs.push(`*-goal.md files in ${name}`);
26
+ }
27
+ return signs;
28
+ }
29
+
30
+ /** @type {typeof import('./planning-folder.d.mts').planningFolderConflict} */
31
+ export function planningFolderConflict(projectRoot) {
32
+ const signs = foreignPlanningFolderSigns(projectRoot);
33
+ if (signs.length === 0) return null;
34
+ return Object.freeze({
35
+ code: 'E_PLANNING_FOLDER_FOREIGN',
36
+ problem: `The ${PLANNING_FOLDER} folder in this project wasn't created by OpenPlanr: it has ${signs.join(', ')} and no OpenPlanr config.json. OpenPlanr wrote nothing there.`,
37
+ fix: `Move or rename that folder, or use ${CLI_COMMAND} in a project without it, then retry.`,
38
+ signs: Object.freeze(signs),
39
+ });
40
+ }