@zmskco/dsh-notebook 0.1.0 → 0.3.0

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/lib/http/api.js CHANGED
@@ -2,7 +2,7 @@ import { NotebookError, asNotebookError } from '../errors.js';
2
2
  import { assertPathName, assertRelativePath } from '../story/paths.js';
3
3
  import { assessWriteAccess, writeAccessGuidance } from '../story/sandbox.js';
4
4
  import { WORKSPACE_PROJECT } from '../story/project.js';
5
- import { workspaceDirFor, workspaceStore } from '../story/workspace.js';
5
+ import { workspaceStore } from '../story/workspace.js';
6
6
  import { revealCommand, revealInFileManager } from './reveal.js';
7
7
  import { workspaceReadme } from '../story/readme.js';
8
8
  import { STATUS_BY_CODE } from './status.js';
@@ -19,6 +19,22 @@ function failure(error) {
19
19
  const body = { code: notebookError.code, message: notebookError.message };
20
20
  return json(body, STATUS_BY_CODE[notebookError.code]);
21
21
  }
22
+ /**
23
+ * Refuse a mutation on a deployment that cannot write.
24
+ *
25
+ * `ctx.fs` refuses a file write on its own (the policy is stamped on it), but a
26
+ * directory is changed through `node:fs`, which no policy guards. Without this
27
+ * check a read-only deployment would silently allow "new folder", rename and
28
+ * delete — three operations whose refusal every other write in the panel already
29
+ * explains with the same guidance.
30
+ * @param access - this request's write assessment.
31
+ * @param workspaceDir - the directory it was assessed against, for the message.
32
+ */
33
+ function refuseReadOnly(access, workspaceDir) {
34
+ if (access.writable)
35
+ return;
36
+ throw new NotebookError('forbidden', writeAccessGuidance(workspaceDir, access) ?? 'this workspace is read-only');
37
+ }
22
38
  /**
23
39
  * Read one JSON request body.
24
40
  *
@@ -55,8 +71,9 @@ export function registerApi(deps) {
55
71
  // may send none, and then the activation fallback applies.
56
72
  const sessionId = url.searchParams.get('session') ?? undefined;
57
73
  const { root, session } = roots(sessionId);
58
- // The panel's directory column is rooted at the workspace itself.
59
- const workspaceDir = workspaceDirFor(session, root.dir);
74
+ // The panel's directory column is rooted at the workspace itself, and that
75
+ // workspace *is* the root: one directory, resolved once for this request.
76
+ const workspaceDir = root.dir;
60
77
  const workspace = workspaceStore({ fs, policy, log }, session, workspaceDir);
61
78
  const open = async (name) => {
62
79
  if (name === WORKSPACE_PROJECT)
@@ -69,7 +86,6 @@ export function registerApi(deps) {
69
86
  case 'state': {
70
87
  return json({
71
88
  rootDir: workspaceDir,
72
- rootSource: root.source,
73
89
  sandbox: {
74
90
  mode: access.mode ?? null,
75
91
  workspaceRoot: access.workspaceRoot ?? null,
@@ -83,7 +99,11 @@ export function registerApi(deps) {
83
99
  }
84
100
  case 'files': {
85
101
  const { store, project } = await open(url.searchParams.get('project'));
86
- return json({ project: project.id, files: await store.listFiles(project) });
102
+ // `truncated` travels with the listing: the tree stops at an entry cap,
103
+ // and a capped list reported as a complete one would have the panel show
104
+ // a folder as empty when it is only large.
105
+ const listing = await store.listFiles(project);
106
+ return json({ project: project.id, files: listing.files, truncated: listing.truncated });
87
107
  }
88
108
  case 'file': {
89
109
  const { store, project } = await open(url.searchParams.get('project'));
@@ -135,19 +155,54 @@ export function registerApi(deps) {
135
155
  return json({ project: project.id, dir: project.abs, focused });
136
156
  }
137
157
  case 'reveal': {
138
- // Show the workspace in the OS file manager. The directory is always the
139
- // one this request resolved to; no path is ever taken from the client, so
140
- // the panel cannot be talked into opening somewhere else. `dryRun` is the
141
- // test hook: it answers what would be launched without launching it.
158
+ // Show the workspace in the OS file manager. The path is optional and, when
159
+ // given, is resolved and re-checked against the workspace before anything is
160
+ // opened — so the panel can reveal a folder (or the folder holding a file)
161
+ // without the browser ever naming a directory the Host did not prove is
162
+ // inside the tree it shows. `dryRun` is the test hook: it answers what
163
+ // would be launched without launching it.
142
164
  const body = await readBody(request);
165
+ const wanted = typeof body.path === 'string' && body.path.length > 0
166
+ ? assertRelativePath(body.path)
167
+ : '';
168
+ const { project } = await open(WORKSPACE_PROJECT);
169
+ const target = await workspace.revealDirectoryFor(project, wanted);
143
170
  if (body.dryRun === true) {
144
- const launch = revealCommand(process.platform, workspaceDir);
145
- return json({ dir: workspaceDir, command: launch.command, args: launch.args, opened: false });
171
+ const launch = revealCommand(process.platform, target);
172
+ return json({ dir: target, command: launch.command, args: launch.args, opened: false });
146
173
  }
147
- const opened = await revealInFileManager(workspaceDir);
174
+ const opened = await revealInFileManager(target);
148
175
  if (!opened)
149
- log.warn(`cannot open a file manager for ${workspaceDir}`);
150
- return json({ dir: workspaceDir, opened });
176
+ log.warn(`cannot open a file manager for ${target}`);
177
+ return json({ dir: target, opened });
178
+ }
179
+ case 'rename': {
180
+ // One entry, in place: the new name is a single segment, so this cannot
181
+ // move a chapter folder somewhere else in the tree.
182
+ const body = await readBody(request);
183
+ const { store, project } = await open(body.project);
184
+ const path = assertRelativePath(typeof body.path === 'string' ? body.path : '');
185
+ const name = assertPathName(body.name);
186
+ refuseReadOnly(access, workspaceDir);
187
+ const renamed = await store.renameEntry(project, path, name);
188
+ return json({ ...renamed, from: path });
189
+ }
190
+ case 'delete': {
191
+ // Irreversible, so the answer says what went: the panel asks first and
192
+ // needs to tell the author what the confirmation actually removed.
193
+ const body = await readBody(request);
194
+ const { store, project } = await open(body.project);
195
+ const path = assertRelativePath(typeof body.path === 'string' ? body.path : '');
196
+ refuseReadOnly(access, workspaceDir);
197
+ const removed = await store.deleteEntry(project, path);
198
+ return json(removed);
199
+ }
200
+ case 'count': {
201
+ // How much a delete would take, for the confirmation. Read-only, so it is
202
+ // answered even on a deployment that refuses the delete itself.
203
+ const { store, project } = await open(url.searchParams.get('project'));
204
+ const path = assertRelativePath(url.searchParams.get('path') ?? '');
205
+ return json({ path, files: await store.countFilesUnder(project, path) });
151
206
  }
152
207
  case 'ensure-readme': {
153
208
  // The one file the panel adds to a workspace on first open. Never an
package/lib/index.js CHANGED
@@ -10,8 +10,7 @@
10
10
  * keeps the plugin inactive — rather than broken — in a profile that has no web
11
11
  * carrier.
12
12
  */
13
- import { defaultRootDir } from './story/bootstrap.js';
14
- import { resolveConfig } from './config.js';
13
+ import { fallbackRootDir } from './story/bootstrap.js';
15
14
  import { API_PATH, registerApi } from './http/api.js';
16
15
  import { createRootResolver } from './story/root.js';
17
16
  import { createFocus } from './story/focus.js';
@@ -27,17 +26,31 @@ export const inject = ['fs', 'webServer', 'connection'];
27
26
  /**
28
27
  * Activate the plugin.
29
28
  * @param ctx - the owning context; every registration below is an effect of it.
30
- * @param rawConfig - the Loader row's `config`, unvalidated by design.
29
+ * @param rawConfig - the Loader row's `config`, which this plugin no longer has.
30
+ * It is read only to warn about a row still carrying the retired `rootDir`:
31
+ * silently ignoring it would leave a profile that looks pinned to a directory
32
+ * the panel is not showing.
31
33
  */
32
34
  export function apply(ctx, rawConfig) {
33
35
  const log = ctx.logger;
34
36
  const policy = ctx.get('sandboxPolicy');
35
- const config = resolveConfig(rawConfig, defaultRootDir(policy), (message) => { log.warn(`notebook: ${message}`); }, policy?.workspaceRoot);
37
+ const configured = typeof rawConfig === 'object' && rawConfig !== null
38
+ ? rawConfig
39
+ : {};
40
+ if (configured.rootDir !== undefined) {
41
+ log.warn('notebook: rootDir is no longer a configuration field; the tree follows the workspace. '
42
+ + 'To keep a notebook somewhere else, open that directory as the workspace.');
43
+ }
44
+ for (const field of Object.keys(configured)) {
45
+ if (field !== 'rootDir')
46
+ log.warn(`notebook: unknown configuration field ${field}; this plugin takes none`);
47
+ }
48
+ const fallbackRoot = fallbackRootDir(policy);
36
49
  // The root is resolved per call rather than here: it follows the workspace of
37
50
  // the Session making the call, so one plugin instance serves every workspace in
38
51
  // the profile instead of pinning one mutable root. See `root.ts` for the rule
39
52
  // and the per-root write policy it stamps.
40
- const roots = createRootResolver({ fs: ctx.fs, config, policy, agents: ctx.get('agents'), log });
53
+ const roots = createRootResolver({ fs: ctx.fs, fallbackRoot, policy, agents: ctx.get('agents'), log });
41
54
  const initialRoot = roots().root;
42
55
  const access = assessWriteAccess(initialRoot.dir, policy);
43
56
  // Puts the Session into the directory the panel shows, so the model's relative
@@ -52,7 +65,7 @@ export function apply(ctx, rawConfig) {
52
65
  // A session-less activation. The panel and every call resolve their own root
53
66
  // from the Session that made the call, so this fallback is what a scripted
54
67
  // caller with no Session would see.
55
- log.info(`notebook: no pinned root and no Session at activation; fallback root is ${initialRoot.dir}`);
68
+ log.info(`notebook: no Session at activation; fallback root is ${initialRoot.dir}`);
56
69
  }
57
70
  if (policy === undefined) {
58
71
  log.info('notebook: no sandbox-policy service in this profile; writes are unconfined');
@@ -62,8 +75,6 @@ export function apply(ctx, rawConfig) {
62
75
  // deployment value: each write stamps `{ mode, workspaceRoot: <that root> }`
63
76
  // (see `sandbox.ts`). The mode, though, is the Session's own.
64
77
  log.info(`notebook: writes allowed (mode=${String(access.mode)}, boundary=each call's root)`);
65
- if (access.reason === 'outside-workspace')
66
- log.warn(`notebook: ${String(writeAccessGuidance(initialRoot.dir, access))}`);
67
78
  }
68
79
  else {
69
80
  // Worth a warning rather than an error: the plugin still mounts and still
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * The directory a session-less caller falls back to.
3
3
  *
4
- * Stories live **in the workspace the operator opened** (see `root.ts`), so this
4
+ * Notes live **in the workspace the operator opened** (see `root.ts`), so this
5
5
  * module covers only what is left over: the directory a caller with no Session at
6
6
  * all falls back to.
7
7
  *
@@ -11,19 +11,14 @@
11
11
  * here either; the workspace's `README.md` is written on first open by
12
12
  * `op=ensure-readme`, which is the one file the panel adds rather than a scaffold
13
13
  * of empty folders.
14
- *
15
- * A `rootDir` in the profile row is still honoured, and is the one way to pin a
16
- * library that several workspaces share. It is a configuration edit — the plugin
17
- * no longer writes its own row, so no Loader reconciliation happens mid-request
18
- * and no service has to exist for the panel to work.
19
14
  */
20
15
  import { homedir } from 'node:os';
21
16
  import { join } from 'node:path';
22
17
  /**
23
- * Where stories live when nothing resolves a root.
18
+ * Where notes live when no Session resolves a root.
24
19
  *
25
20
  * Used only for a session-less caller: the panel and every tool call carry a
26
- * Session, and that Session's workspace is the story root. Chosen inside the
21
+ * Session, and that Session's workspace is the root. Chosen inside the
27
22
  * deployment's write boundary so that even this last resort is writable.
28
23
  *
29
24
  * `workingDirectory.defaultDirectory` is deliberately not consulted. Its own
@@ -33,7 +28,7 @@ import { join } from 'node:path';
33
28
  * @param policy - the sandbox policy service, when this profile has one.
34
29
  * @returns an absolute directory path; it need not exist yet.
35
30
  */
36
- export function defaultRootDir(policy) {
31
+ export function fallbackRootDir(policy) {
37
32
  const boundary = policy?.workspaceRoot;
38
33
  if (boundary !== undefined && boundary.trim().length > 0)
39
34
  return boundary.trim();
@@ -2,34 +2,157 @@
2
2
  * What the notebook's tree shows, and how a file is read back.
3
3
  *
4
4
  * The format layer, kept apart from the IO that serves it: everything here is
5
- * pure — which names the browser may open, how a text is counted — and the store
5
+ * pure — which names the editor may open, how a text is counted — and the store
6
6
  * in `project.ts` owns the filesystem, the sandbox policy and the listing.
7
7
  *
8
+ * **The tree lists everything under the directory.** It used to run an extension
9
+ * allowlist (`md`, `txt`, `json`, …), which hid the code an author works next to and
10
+ * then, after that was widened, still hid every binary — and a tree that hides a
11
+ * file the filesystem has is a tree the user cannot trust: "my file is not there"
12
+ * is the report it produces. So every regular file is listed, and the two questions
13
+ * are answered separately:
14
+ *
15
+ * - **Is it text?** ({@link classifyFileName} + {@link isProbablyText}) — a known
16
+ * text type is text, a known binary type is binary, and anything else is decided
17
+ * by its first bytes.
18
+ * - **May it be opened?** A `binary` entry is listed as `binary` and the panel says
19
+ * why it cannot be previewed, instead of the row being absent.
20
+ *
8
21
  * @module notebook/story/manuscript
9
22
  */
10
23
  import { basename } from 'node:path';
11
24
  /** Deepest nesting the tree descends into. */
12
- export const MAX_TREE_DEPTH = 8;
25
+ export const MAX_TREE_DEPTH = 12;
13
26
  /** Ceiling on files listed for one root, so a huge tree cannot stall the page. */
14
- export const MAX_TREE_ENTRIES = 2_000;
15
- /** Extensions the browser opens as editable text. */
16
- export const TEXT_EXTENSIONS = new Set(['.md', '.markdown', '.txt', '.json', '.jsonl', '.yml', '.yaml', '.csv']);
27
+ export const MAX_TREE_ENTRIES = 4_000;
28
+ /**
29
+ * How many bytes of an unknown file are sniffed to decide whether it is text.
30
+ *
31
+ * One page is enough to meet the NUL byte of an image, an archive or a compiled
32
+ * binary, and small enough that a listing of a few hundred unknown files is one
33
+ * handful of reads rather than a directory-sized download.
34
+ */
35
+ export const SNIFF_BYTES = 4_096;
36
+ /**
37
+ * Extensions the tree accepts without looking at the bytes.
38
+ *
39
+ * This is an optimization and a default, not the boundary: a name outside it is
40
+ * sniffed rather than refused, so a file type nobody listed still opens when its
41
+ * content is text. The one list that *does* refuse is {@link BINARY_EXTENSIONS}.
42
+ */
43
+ export const TEXT_EXTENSIONS = new Set([
44
+ // Prose and documents.
45
+ '.md', '.markdown', '.mdx', '.txt', '.text', '.rst', '.adoc', '.asciidoc', '.tex', '.org',
46
+ // Data and configuration.
47
+ '.json', '.jsonl', '.jsonc', '.ndjson', '.json5', '.yml', '.yaml', '.toml', '.ini', '.cfg',
48
+ '.conf', '.properties', '.csv', '.tsv', '.xml', '.env', '.diff', '.patch', '.log', '.map',
49
+ // Markup and style.
50
+ '.html', '.htm', '.xhtml', '.css', '.scss', '.sass', '.less', '.styl', '.svg',
51
+ // Source code.
52
+ '.js', '.mjs', '.cjs', '.jsx', '.ts', '.mts', '.cts', '.tsx', '.vue', '.svelte', '.astro',
53
+ '.py', '.rb', '.php', '.go', '.rs', '.java', '.kt', '.kts', '.swift', '.scala', '.groovy',
54
+ '.gradle', '.c', '.h', '.cc', '.cpp', '.cxx', '.hpp', '.hh', '.cs', '.fs', '.fsx', '.lua',
55
+ '.r', '.dart', '.ex', '.exs', '.erl', '.hrl', '.hs', '.clj', '.cljs', '.pl', '.pm', '.zig',
56
+ '.nim', '.jl', '.sh', '.bash', '.zsh', '.fish', '.ps1', '.psm1', '.bat', '.cmd', '.sql',
57
+ '.graphql', '.gql', '.tf', '.hcl', '.nix', '.cmake', '.mk', '.asm', '.s', '.vim', '.sol',
58
+ '.elm', '.v',
59
+ ]);
60
+ /**
61
+ * Extensions the tree never shows, whatever their bytes say.
62
+ *
63
+ * Sniffing would catch most of these anyway — a PNG meets a NUL byte in its
64
+ * header — but a name is free and a read is not: the listing asks the filesystem
65
+ * for a window per unknown file, and images, media and archives are exactly the
66
+ * bulk a workspace of notes accumulates. Everything here is a format whose bytes
67
+ * are not text by construction.
68
+ */
69
+ export const BINARY_EXTENSIONS = new Set([
70
+ // Images.
71
+ '.png', '.jpg', '.jpeg', '.jfif', '.gif', '.webp', '.avif', '.bmp', '.ico', '.icns',
72
+ '.tif', '.tiff', '.psd', '.xcf', '.heic', '.heif', '.raw', '.cr2', '.nef',
73
+ // Documents that are containers rather than text.
74
+ '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx', '.odt', '.ods', '.odp',
75
+ '.epub', '.mobi', '.azw3',
76
+ // Archives and packages.
77
+ '.zip', '.gz', '.tgz', '.bz2', '.xz', '.7z', '.rar', '.tar', '.zst', '.lz4', '.jar', '.war',
78
+ '.apk', '.ipa', '.nupkg', '.vsix', '.deb', '.rpm', '.msi', '.dmg', '.iso', '.squashfs',
79
+ // Compiled and native.
80
+ '.exe', '.dll', '.so', '.dylib', '.bin', '.wasm', '.class', '.o', '.obj', '.a', '.lib',
81
+ '.pdb', '.pyd', '.pyc', '.pyo', '.node', '.elf', '.pak',
82
+ // Audio and video.
83
+ '.mp3', '.wav', '.flac', '.aac', '.ogg', '.oga', '.opus', '.m4a', '.wma', '.mid', '.midi',
84
+ '.mp4', '.m4v', '.mov', '.avi', '.mkv', '.webm', '.wmv', '.flv', '.mpg', '.mpeg', '.3gp',
85
+ // Fonts.
86
+ '.woff', '.woff2', '.ttf', '.otf', '.eot', '.ttc',
87
+ // Databases and binary data sets.
88
+ '.sqlite', '.sqlite3', '.db', '.mdb', '.lmdb', '.parquet', '.avro', '.orc', '.arrow',
89
+ '.npy', '.npz', '.pkl', '.pickle', '.h5', '.hdf5', '.mat', '.sav', '.dta', '.glb', '.fbx',
90
+ ]);
17
91
  /**
18
- * Whether a file is text the editor may open.
92
+ * Classify one file by its name.
19
93
  *
20
- * An allowlist rather than a denylist: a working directory accumulates images,
21
- * archives and OS droppings, and showing all of it would bury the notes. A bare
22
- * name has no extension at all — the panel names files by title (`第一章`) — and
23
- * a title is a text file; only an *unknown* extension is refused.
94
+ * A bare name has no extension at all — the panel names files by title (`第一章`)
95
+ * — and a title is a text file. `.bashrc`-style names are skipped by the listing
96
+ * before this is asked, and a name that starts with a dot has no extension to read
97
+ * here either, so `dot <= 0` is the "no suffix" case.
24
98
  * @param path - project-relative path; only its basename is considered.
25
- * @returns true when the file is editable text.
99
+ * @returns `text`, `binary`, or `unknown` (decide by content).
26
100
  */
27
- export function isTextFile(path) {
101
+ export function classifyFileName(path) {
28
102
  const name = basename(path);
29
103
  const dot = name.lastIndexOf('.');
30
104
  if (dot <= 0)
31
- return true;
32
- return TEXT_EXTENSIONS.has(name.slice(dot).toLowerCase());
105
+ return 'text';
106
+ const extension = name.slice(dot).toLowerCase();
107
+ if (TEXT_EXTENSIONS.has(extension))
108
+ return 'text';
109
+ if (BINARY_EXTENSIONS.has(extension))
110
+ return 'binary';
111
+ return 'unknown';
112
+ }
113
+ /**
114
+ * Whether a name is a text type as far as its extension goes.
115
+ *
116
+ * `unknown` counts as text: the extension said nothing, so only the bytes can, and
117
+ * that read happens against the file rather than the name. The store sniffs an
118
+ * `unknown` file before deciding what to list it as; a binary type is the only
119
+ * thing this predicate turns down.
120
+ * @param path - project-relative path; only its basename is considered.
121
+ * @returns false only for a name known to be binary.
122
+ */
123
+ export function isTextFile(path) {
124
+ return classifyFileName(path) !== 'binary';
125
+ }
126
+ /**
127
+ * Whether a window of bytes looks like text.
128
+ *
129
+ * Two facts decide it, and neither needs the bytes to be UTF-8:
130
+ *
131
+ * - **A NUL byte.** No text format carries one; every binary one this list can
132
+ * meet — images, archives, executables, fonts, media — does, usually within the
133
+ * first few dozen bytes.
134
+ * - **A C0 control other than tab, line feed, vertical tab, form feed and carriage
135
+ * return.** That is the rest of "binary junk" that has no NUL early.
136
+ *
137
+ * Deliberately **not** a UTF-8 validity check: a workspace may hold a Chinese file
138
+ * in GBK or GB18030, which is text a reader expects to open even though it is not
139
+ * UTF-8, and refusing it would hide the author's own notes. The editor decodes
140
+ * whatever the filesystem provider returns.
141
+ * @param head - the first bytes of the file; empty is an empty file, which is text.
142
+ * @returns true when the window passes for text.
143
+ */
144
+ export function isProbablyText(head) {
145
+ for (const byte of head) {
146
+ if (byte === 0)
147
+ return false;
148
+ if (byte < 0x09)
149
+ return false;
150
+ if (byte > 0x0d && byte < 0x20)
151
+ return false;
152
+ if (byte === 0x7f)
153
+ return false;
154
+ }
155
+ return true;
33
156
  }
34
157
  /** Whether an error means "the file is not there". */
35
158
  export function isMissing(error) {