@g3nomaly/core 0.3.2 → 0.3.3

package/README.md

@@ -0,0 +1,122 @@
+# @g3nomaly/core
+
+`@g3nomaly/core` is the shared runtime behind the g3n installers: [`@g3nomaly/ui`](https://www.npmjs.com/package/@g3nomaly/ui), [`@g3nomaly/mods`](https://www.npmjs.com/package/@g3nomaly/mods) and [`@g3nomaly/skills`](https://www.npmjs.com/package/@g3nomaly/skills). It reads sources from git, npm or a local folder, copies entries into a project, records them in an install manifest and runs the `add`, `update`, `remove`, `ls` and `source` commands those installers share. Use it to build an installer of your own, or to reuse one piece, such as file hashing or the `.g3n.config.json` loader.
+
+## Requirements
+
+- [Bun](https://bun.sh). Core calls `Bun.file` and `Bun.Transpiler`, so it does not run on Node.
+- A CLI or script. `hash` and `config` throw when loaded in a browser.
+
+```sh
+bun add @g3nomaly/core
+```
+
+## What each import gives you
+
+Import from a subpath. The package root exports nothing.
+
+| Import | What it gives you |
+|---|---|
+| `@g3nomaly/core/hash` | SHA-256 of a file or a string, full or 12 characters |
+| `@g3nomaly/core/registry` | A typed registry of entries on a TanStack Store, saved as `.ts` or `.json`, and the base entry schemas |
+| `@g3nomaly/core/config` | Read and write `.g3n.config.json`, with defaults for every section |
+| `@g3nomaly/core/security` | `getSafeObject`, which reads the object a `.ts` file exports without importing the file |
+| `@g3nomaly/core/sources` | Parse `owner/repo`, `npm:pkg` or `./folder` into a source spec and check it out to a folder |
+| `@g3nomaly/core/installer` | Install manifests, reading every source into one registry, resolving names and dependencies, copying files |
+| `@g3nomaly/core/cli` | The shared commands, the prompts they ask, and the terminal theme |
+| `@g3nomaly/core/utils` | `findGitRoot`, `findUp`, `readPackageMeta`, `warnIfOutdated`, `errorMessage` |
+
+## Hashes and registries
+
+An installer hashes each file it copies, so a later `update` can tell which files you changed.
+
+```ts
+import { hashFile } from "@g3nomaly/core/hash";
+import { createRegistryStore, flush, jsonHandler, load, register } from "@g3nomaly/core/registry";
+
+const registry = createRegistryStore({ filePath: "/home/me/app/.installed.json", handler: jsonHandler });
+await load(registry); // a missing file leaves the store empty
+
+register(registry, "button", {
+  name: "button",
+  files: [{ path: "button.tsx", type: "component", hash: await hashFile("/home/me/app/src/button.tsx") }],
+});
+flush(registry); // writes the entries back, sorted by key
+```
+
+`registry.store` is the TanStack Store itself, so you can subscribe to it. Without a handler, `flush` writes a `.ts` file that exports `registry`. Packages add their own fields by extending `BaseRegistryEntrySchema` and `BaseFileEntrySchema`.
+
+## Project config
+
+`.g3n.config.json` holds one section per package: `g3nui`, `g3nerate` and `skills`. `loadConfig` fills in every default. `saveConfig` writes only the sections already in the file or named in the update, so one package's `init` never writes another package's section.
+
+```ts
+import { loadConfig, resolveProjectRoot, saveConfig } from "@g3nomaly/core/config";
+
+const root = resolveProjectRoot() ?? process.cwd(); // nearest folder with .g3n.config.json or .git
+const { skills } = await loadConfig(root);
+await saveConfig(root, { skills: { settings: { targets: ["claude", "codex"] } } });
+```
+
+## Reading a `.ts` file safely
+
+`getSafeObject(filePath, schema, timeoutMs = 1000)` takes the object literal a file exports, evaluates it in a worker and checks the result against the zod schema. It refuses source with `eval`, dynamic `import()` or a nested-quantifier regex, and a result holding functions or too many keys. It drops getters without running them.
+
+## Building an installer
+
+An installer supplies three things: a zod schema for its entries, a function that reads the entries in one checked-out source, and the folder they install into.
+
+```ts
+import path from "node:path";
+import { z } from "zod";
+import { BaseFileEntrySchema } from "@g3nomaly/core/registry";
+import { listFiles, loadInstallManifest, loadSourceRegistry, manifestSources, OriginEntrySchema, type ReadSource } from "@g3nomaly/core/installer";
+import { addFromSources, reportSourceRegistry } from "@g3nomaly/core/cli";
+
+const PromptSchema = OriginEntrySchema.extend({
+  files: z.array(BaseFileEntrySchema.extend({ type: z.literal("prompt") })).min(1),
+});
+type Prompt = z.infer<typeof PromptSchema>;
+
+// Each file under prompts/ in a source is one entry.
+const readPrompts: ReadSource<Prompt> = async (checkout) => ({
+  entries: listFiles(path.join(checkout.dir, "prompts")).map((file): [string, Prompt] => {
+    const name = path.basename(file, ".md");
+    return [name, {
+      name,
+      origin: { source: checkout.name, dir: "prompts", commit: checkout.commit, version: checkout.version },
+      files: [{ path: file, type: "prompt" }],
+    }];
+  }),
+  warnings: [],
+});
+
+const root     = "/home/me/app";
+const manifest = loadInstallManifest(path.join(root, ".prompts.json"), PromptSchema);
+const target   = { label: "project", installDir: path.join(root, "prompts"), store: manifest.store, manifest };
+const builtins = { "my-prompts": { kind: "git" as const, url: "https://github.com/me/prompts.git" } };
+
+const registry = await loadSourceRegistry(manifestSources([manifest], builtins), root, readPrompts);
+reportSourceRegistry(registry); // prints warnings and the sources that failed to load
+try {
+  await addFromSources([target], ["review"], registry, {}, { bin: "my-prompts", noun: "prompt", entrySchema: PromptSchema });
+} finally {
+  registry.dispose(); // removes temporary checkouts
+}
+```
+
+`addFromSources` resolves `review` or `review@my-prompts` across every source, installs its `registryDependencies`, asks before it overwrites a file you changed, and saves `.prompts.json`. `updateFromSources`, `removeFromTargets`, `addSourceEntries`, `lsSources`, `removeSourceEntries`, `lsSourceRegistry` and `lsEntries` cover the other commands. The CLI of [`@g3nomaly/mods`](https://www.npmjs.com/package/@g3nomaly/mods) is a working example, built from these calls.
+
+## Development
+
+Run `bun install` at the repository root first, then every command from this directory.
+
+```sh
+bun run build      # dist/
+bun run typecheck
+bun test
+```
+
+## License
+
+Elastic License 2.0. See `LICENSE`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@g3nomaly/core",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Shared runtime for @g3n packages — hashing, registry, security, config",
   "type": "module",
   "main": "./dist/index.js",