acrylblends 0.7.6 → 0.7.7

package/plugins/acryl-kv-json/src/open.ts

@@ -0,0 +1,185 @@
+/**
+ * The plain way to open the JSON-file provider, for code without Cordis (an acrylblends app): `openKv({ path })` reads one JSON file into
+ * memory and resolves the `kv` port with the function that closes it. The Cordis plugin is a thin wrapper over this, so both run one code
+ * path. This entry imports nothing from Cordis.
+ *
+ * Every write queues behind the writes before it and persists the whole map: serialize to a temporary file in the same folder, flush it,
+ * rename it over the file, and flush the folder where the platform allows. The call resolves after the rename, so a crash leaves the old file
+ * or the new one, never half of one. One process owns the file: two writers would overwrite each other.
+ */
+
+import { mkdir, open, readdir, readFile, rename, rm } from 'node:fs/promises'
+import { basename, dirname, join, resolve } from 'node:path'
+import { checkKey, compareKeys, decodeValue, encodeValue, type Kv, type KvOpened, runChange } from '../../acryl-kv/src/index.ts'
+
+export type { Kv, KvOpened } from '../../acryl-kv/src/index.ts'
+
+export interface OpenKvOptions {
+  /** The JSON file; its folder is created if missing. */
+  readonly path: string
+}
+
+/** The file's own format version, for a later change of layout. */
+const FORMAT = 1
+
+/** Stray temporary files from a crash end in `.tmp` and start with the file's name. */
+const tempPrefix = (file: string): string => `${basename(file)}.`
+
+/** The file content for a map of key to JSON text, keys in code point order, so the same data is the same bytes. */
+function serialize(entries: ReadonlyMap<string, string>): string {
+  const body = [...entries.keys()].sort(compareKeys).map(key => `${JSON.stringify(key)}:${entries.get(key)}`).join(',')
+  return `{"version":${FORMAT},"entries":{${body}}}\n`
+}
+
+function unreadable(file: string, reason: string): Error {
+  return new Error(`acryl-kv-json: ${file} is not a readable kv file (${reason}); it was not changed`)
+}
+
+/** The entries of a file, or none when it does not exist. A file that exists and does not parse is an error: it is never started over. */
+async function load(file: string): Promise<Map<string, string>> {
+  let text: string
+  try {
+    text = await readFile(file, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return new Map()
+    throw error
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch (error) {
+    throw unreadable(file, (error as Error).message)
+  }
+  if (typeof parsed !== 'object' || parsed === null || (parsed as { version?: unknown }).version !== FORMAT) throw unreadable(file, 'not a version 1 kv file')
+  const entries = (parsed as { entries?: unknown }).entries
+  if (typeof entries !== 'object' || entries === null || Array.isArray(entries)) throw unreadable(file, 'no entries object')
+  return new Map(Object.entries(entries).map(([key, value]) => [key, JSON.stringify(value)]))
+}
+
+/** Remove the temporary files an earlier crash left beside the file. */
+async function removeStrays(file: string): Promise<void> {
+  const prefix = tempPrefix(file)
+  for (const name of await readdir(dirname(file))) {
+    if (name.startsWith(prefix) && name.endsWith('.tmp')) await rm(join(dirname(file), name), { force: true })
+  }
+}
+
+const RENAME_RETRIES = 8
+
+/** Rename over the target. Windows refuses while a scanner or an indexer holds the target for a moment, so it is retried briefly. */
+async function replace(from: string, to: string): Promise<void> {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      await rename(from, to)
+      return
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code
+      if (attempt >= RENAME_RETRIES || (code !== 'EPERM' && code !== 'EBUSY' && code !== 'EACCES')) throw error
+      await new Promise(resolveWait => setTimeout(resolveWait, 10 * (attempt + 1)))
+    }
+  }
+}
+
+/** Flush the folder entry of a renamed file (POSIX); Windows cannot open a folder, and a filesystem that refuses is no worse than before. */
+async function flushFolder(folder: string): Promise<void> {
+  if (process.platform === 'win32') return
+  try {
+    const handle = await open(folder, 'r')
+    try {
+      await handle.sync()
+    } finally {
+      await handle.close()
+    }
+  } catch {
+    // Best effort: the rename itself is already atomic.
+  }
+}
+
+/** Open (and create, when missing) a JSON-file store. @throws when the file exists and is not a readable kv file. */
+export async function openKv(options: OpenKvOptions): Promise<KvOpened> {
+  const file = resolve(options.path)
+  await mkdir(dirname(file), { recursive: true })
+  await removeStrays(file)
+  let state = await load(file)
+  let closed = false
+  let sequence = 0
+  let tail: Promise<unknown> = Promise.resolve()
+
+  const guard = (): void => {
+    if (closed) throw new Error(`acryl-kv-json: ${file} is closed`)
+  }
+
+  /** Persist a map: the file is the old one or this one, never between. */
+  const persist = async (next: ReadonlyMap<string, string>): Promise<void> => {
+    sequence += 1
+    const temp = join(dirname(file), `${tempPrefix(file)}${process.pid}.${sequence}.tmp`)
+    try {
+      const handle = await open(temp, 'w')
+      try {
+        await handle.writeFile(serialize(next), 'utf8')
+        await handle.sync()
+      } finally {
+        await handle.close()
+      }
+      await replace(temp, file)
+    } catch (error) {
+      await rm(temp, { force: true })
+      throw error
+    }
+    await flushFolder(dirname(file))
+  }
+
+  /** Run a change after every earlier one; the map it works on becomes the state only once it is on disk. */
+  const write = <T>(change: (draft: Map<string, string>) => T): Promise<T> => {
+    guard()
+    const task = tail.then(async () => {
+      const draft = new Map(state)
+      const result = change(draft)
+      await persist(draft)
+      state = draft
+      return result
+    })
+    tail = task.catch(() => undefined)
+    return task
+  }
+
+  const kv: Kv = {
+    async get<T>(key: string) {
+      guard()
+      checkKey(key)
+      const text = state.get(key)
+      return text === undefined ? undefined : decodeValue<T>(text)
+    },
+    async set(key, value) {
+      checkKey(key)
+      const text = encodeValue(value)
+      await write(draft => { draft.set(key, text) })
+    },
+    async update<T>(key: string, change: (current: T | undefined) => T) {
+      checkKey(key)
+      return write(draft => {
+        const text = draft.get(key)
+        const next = runChange(change, text === undefined ? undefined : decodeValue<T>(text))
+        const encoded = encodeValue(next)
+        draft.set(key, encoded)
+        return decodeValue<T>(encoded)
+      })
+    },
+    async delete(key) {
+      checkKey(key)
+      await write(draft => { draft.delete(key) })
+    },
+    async list(prefix = '') {
+      guard()
+      return [...state.keys()].filter(key => key.startsWith(prefix)).sort(compareKeys)
+    },
+  }
+
+  return {
+    kv,
+    close: async () => {
+      closed = true
+      await tail
+    },
+  }
+}

package/plugins/acryl-kv-json/upstream.json

@@ -0,0 +1,22 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "path": "plugins/acryl-kv-json",
+    "commit": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
+  },
+  "vendored": [
+    "src",
+    "tests",
+    "LICENSE"
+  ],
+  "rewrittenSpecifiers": 6,
+  "digest": "sha256:d8e3e7f9c98399d0f21f29f91323b4ce57646e59e312d4175978259d618a88cf",
+  "testsNotRun": {
+    "tests/loader.spec.ts": "loads the plugin through the real Loader (@deepseek-ai/cordis-plugin-loader), which generated apps do not install; the plain opener it wraps is tested here by open.spec.ts and conformance.spec.ts",
+    "tests/crash.spec.ts": "kills a child process that imports the package build (lib/), which a copy vendored into an app does not have; it runs in ACRYL",
+    "tests/plain-entry-imports.spec.ts": "a copy vendored into an app (with relative imports, no build of its own) has neither `lib/`; the app's own typecheck is what proves the copy names no Cordis type it does not provide."
+  },
+  "notice": [
+    "LICENSE"
+  ]
+}

package/plugins/acryl-node-server/src/index.ts

@@ -93,13 +93,24 @@ export class NodeServer extends Service {
         this.bound = (this.server.address() as AddressInfo).port
         return
       } catch (error) {
-        if ((error as NodeJS.ErrnoException).code !== 'EADDRINUSE') throw error
+        if (!isPortUnavailable(error)) throw error
       }
     }
     throw new Error(`acryl-node-server: no free port from ${String(port)} to ${String(last)} on ${hostname}`)
   }
 }
 
+/**
+ * Whether a failed bind means "this port, try the next one". A port another socket holds answers `EADDRINUSE` everywhere. On Windows a port
+ * inside a range the system reserves (Hyper-V, WSL and Docker exclude ranges, `netsh interface ipv4 show excludedportrange`) answers
+ * `EACCES`, which is a property of that port too; elsewhere `EACCES` means the process may not bind low ports at all, so moving on would
+ * only hide the reason.
+ */
+export function isPortUnavailable(error: unknown, platform: NodeJS.Platform = process.platform): boolean {
+  const code = (error as NodeJS.ErrnoException | undefined)?.code
+  return code === 'EADDRINUSE' || (platform === 'win32' && code === 'EACCES')
+}
+
 /** Loads once the server listens, so a plugin that injects `nodeServer` can rely on `url`. A failure to bind fails the plugin. */
 export async function apply(ctx: Context, config: Partial<Config> = {}): Promise<void> {
   const server = new NodeServer(ctx, { hostname: '127.0.0.1', port: 0, scan: 20, ...config })

package/plugins/acryl-node-server/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-node-server",
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
   },
   "vendored": [
     "src",
@@ -10,7 +10,7 @@
     "LICENSE"
   ],
   "rewrittenSpecifiers": 31,
-  "digest": "sha256:0a3278e006540d0dbecdfb6ada3ca865f3a9a78b649edd9454dab0c76281eda0",
+  "digest": "sha256:e4f98422082758912834a6e454505230a18ac543b4851f6eb697b628a1acec4e",
   "testsNotRun": {
     "tests/client-modules.spec.ts": "links typescript from the plugin's own node_modules (ACRYL's workspace layout); clientModules and build-client are exercised here by the templates' tests and verify:scaffolder",
     "tests/register.spec.ts": "links typescript from the plugin's own node_modules (ACRYL's workspace layout); the hook is exercised here by the templates' own .tsx tests and verify:scaffolder"

package/plugins/acryl-router/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-router",
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
   },
   "vendored": [
     "src",

package/plugins/acryl-router-http/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-router-http",
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
   },
   "vendored": [
     "src",

package/plugins/acryl-state/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-state",
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
   },
   "vendored": [
     "src",

package/plugins/desktop/upstream.json

@@ -5,7 +5,7 @@
       "apps/acryl-desktop/src/shell/desktop-user-data.ts": "user-data.ts",
       "apps/acryl-desktop/src/shell/shutdown.ts": "shutdown.ts"
     },
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
   },
   "rewrittenSpecifiers": 0,
   "digest": "sha256:7dfe960a8bbb476c35540d2202a7aaa62b33492c2ac3e34314e2ecfca45f32f2"

package/plugins/desktop-web/upstream.json

@@ -5,7 +5,7 @@
       "apps/acryl-desktop/src/shell/desktop-user-data.ts": "user-data.ts",
       "apps/acryl-desktop/src/shell/shutdown.ts": "shutdown.ts"
     },
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
   },
   "rewrittenSpecifiers": 0,
   "digest": "sha256:7dfe960a8bbb476c35540d2202a7aaa62b33492c2ac3e34314e2ecfca45f32f2"

package/plugins/tsconfig.json

@@ -24,6 +24,8 @@
     "acryl-node-server/tests/adapter",
     "acryl-router/tests/loader.spec.ts",
     "acryl-db-sqlite/tests/loader.spec.ts",
+    "acryl-kv-json/tests/loader.spec.ts",
+    "acryl-kv-db/tests/loader.spec.ts",
     "acryl-state/src/react.ts",
     "acryl-state/tests/react.spec.ts",
     "acryl-router-http/tests/adapter.spec.ts",

package/templates/todo/upstream.json

@@ -5,7 +5,7 @@
       "examples/acryl-todo/src/index.ts": "src/todo.ts",
       "examples/acryl-todo/src/page.ts": "src/page.ts"
     },
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
   },
   "rewrittenSpecifiers": 4,
   "digest": "sha256:9093704776563001f7f472f94cc5c2fdd79206342c1cb59c11fce62aa74df3ed"

package/lib/index-D4FAsBZu.d.ts

@@ -1,85 +0,0 @@
-//#region ../../plugins/acryl-db/src/facade/database.d.ts
-/** Values supported by the portable SQL drivers. */
-type SqlValue = null | number | bigint | string | Uint8Array;
-/**
- * Asynchronous SQL operations shared by a database and its transaction handles.
- *
- * `exec` runs SQL text without bindings and may contain several statements. `run`, `get`, and `all`
- * execute one statement with positional bindings. Adapters may cache prepared statements by SQL text,
- * so callers pass values as bindings instead of interpolating them. `run` resolves the number of rows
- * the statement changed.
- */
-interface DbExecutor {
-  exec(sql: string): Promise<void>;
-  run(sql: string, ...params: SqlValue[]): Promise<{
-    readonly changes: number;
-  }>;
-  get<T extends object>(sql: string, ...params: SqlValue[]): Promise<T | undefined>;
-  all<T extends object>(sql: string, ...params: SqlValue[]): Promise<T[]>;
-}
-/**
- * Minimal portable SQL database facade.
- *
- * All operations are asynchronous so adapters may execute outside the caller's runtime.
- *
- * `transaction` passes the callback a transaction handle. All work in the transaction
- * must use that handle; the handle is invalid after the callback settles. Adapters must
- * queue unrelated operations and other transactions until the transaction finishes. The
- * returned promise settles after commit or rollback. Calling the database itself (including
- * `transaction`) from inside a callback therefore waits for that transaction and
- * never settles.
- *
- * When the callback rejects, the adapter must roll the transaction back before rejecting
- * with that same error. If rollback fails, it must reject with a different error (for
- * example an `AggregateError`) so callers cannot mistake the callback error for a
- * guaranteed rollback.
- *
- * Closing is the adapter's: the plugin that opened a database closes it, so the facade an
- * app receives has no `close`.
- */
-interface Db extends DbExecutor {
-  transaction<T>(callback: (transaction: DbExecutor) => Promise<T>): Promise<T>;
-}
-//#endregion
-//#region ../../plugins/acryl-db/src/facade/migrations.d.ts
-type Migration = {
-  readonly version: number;
-  readonly statements: readonly string[];
-};
-/**
- * Apply all pending migrations atomically, tracking their version in the named metadata table.
- *
- * The bookkeeping SQL runs unchanged on SQLite and Postgres: no `STRICT` table, `ON CONFLICT DO NOTHING`
- * instead of `INSERT OR IGNORE`, and the version written as a checked integer rather than a binding,
- * since the two dialects spell placeholders differently.
- */
-declare function applyMigrations(database: Db, migrations: readonly Migration[], options: {
-  readonly table: string;
-}): Promise<void>;
-//#endregion
-//#region ../../plugins/acryl-db/src/facade/schema.d.ts
-/** Validate a prefix before using it as part of a SQL identifier. */
-declare function validateSchemaPrefix(prefix: string): void;
-//#endregion
-//#region ../../plugins/acryl-db/src/migration-files.d.ts
-/**
- * Read every `NNN-name.sql` file of a folder, in number order.
- * @throws when a `.sql` file is not named `NNN-name.sql`, or the numbers do not run 1, 2, 3, ... without gaps or repeats.
- */
-declare function readMigrationFiles(folder: string | URL): Promise<Migration[]>;
-//#endregion
-//#region ../../plugins/acryl-db/src/index.d.ts
-/**
- * The `db` port: what an app's code sees of its relational database, whichever provider (`acryl-db-sqlite`, `acryl-db-postgres`) serves
- * it. Plain code (an acrylblends app) opens a database with a provider's `openDb`; a Cordis plugin declares `inject: ['db']`, imports
- * `acryl-db/cordis` for the `ctx.db` type, and never imports a driver.
- *
- * Bindings are positional `?` placeholders on every provider; a provider whose database spells them differently translates them.
- * This entry imports nothing from Cordis, at runtime or in its types.
- */
-/** The service name every `db` provider registers. */
-declare const DB_SERVICE = "db";
-/** The table that records an app's migration version. */
-declare const MIGRATIONS_TABLE = "_migrations";
-//#endregion
-export { Migration as a, DbExecutor as c, validateSchemaPrefix as i, SqlValue as l, MIGRATIONS_TABLE as n, applyMigrations as o, readMigrationFiles as r, Db as s, DB_SERVICE as t };