flowdular 0.1.0 → 0.2.0

package/README.md

@@ -1,30 +1,73 @@
+[![Flowdular: Build your business platform](https://cdn.jsdelivr.net/npm/flowdular@latest/assets/flowdular-banner.png)](https://flowdular.com)
+
 # Flowdular CLI
 
-Manage a Flowdular workspace with the `flowdular` command (`fd` is an alias).
-Create an application first:
+[![npm version](https://img.shields.io/npm/v/flowdular?color=f59e0b)](https://www.npmjs.com/package/flowdular)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22.22.2-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Flowdular/flowdular/blob/main/LICENSE)
+
+Inspect, configure and extend a Flowdular application from your terminal. The CLI manages module validation, source installation, generated composition and workspace diagnostics.
+
+## Quick start
+
+Use Node.js **22.22.2 or newer**. Create a configured pnpm workspace:
 
 ```sh
 npm create flowdular@latest my-app
 cd my-app
 pnpm flowdular doctor
+pnpm flowdular help
+```
+
+The generator includes the CLI. To add it to an existing Flowdular workspace:
+
+```sh
+pnpm add -Dw flowdular
 ```
 
-The npm package is named `flowdular`. The shared platform API and UI are in
-`@flowdular/sdk`; the generator is `create-flowdular`. Internal packages in the
-Flowdular repository are private workspaces and do not require separate npm releases.
+The executable is `flowdular`; `fd` is also available as an alias. Run commands from your application workspace.
+
+## Everyday commands
+
+| Command                                   | Purpose                                         |
+| ----------------------------------------- | ----------------------------------------------- |
+| `pnpm flowdular doctor`                   | Inspect workspace configuration and diagnostics |
+| `pnpm flowdular help`                     | List commands and supported flags               |
+| `pnpm flowdular module search`            | Browse the configured source catalog            |
+| `pnpm flowdular module install <id>`      | Preview a source installation                   |
+| `pnpm flowdular module sync --apply`      | Regenerate application composition              |
+| `pnpm flowdular module validate --locked` | Validate modules against the installation lock  |
+
+## Install a business module
+
+For a catalog containing `expenses.core`:
 
 ```sh
-pnpm flowdular module search
+# Inspect the planned source installation.
 pnpm flowdular module install expenses.core
+
+# Download and unpack the module source.
 pnpm flowdular module install expenses.core --apply
+
+# Enable the module and grant its scopes in the configured application.
 pnpm flowdular module enable expenses.core --apply
+
+# Check the installed modules against their lock.
 pnpm flowdular module validate --locked
 ```
 
-Source installation previews by default and does not activate code or touch a
-database. Official source catalog downloads require access to the repository;
-an explicit local catalog can be supplied with `--registry /path/to/index.json`.
-Use `pnpm flowdular help` for commands, permissions and explicit apply flags.
+Source installation previews by default. Applying it writes source under `modules/`; activation is a separate step. Enabling a module updates application composition and can grant scopes against the configured database.
+
+[Official Modules](https://github.com/Flowdular/official-modules) requires repository access while private. For an accessible local catalog, pass `--registry /absolute/path/to/index.json` to the search or install command. Catalog availability is independent of npm package installation.
+
+## Automation
+
+Release tooling can import the source distribution API through `flowdular/distribution`. Command permissions and apply requirements are documented in the [CLI guide](https://github.com/Flowdular/flowdular/blob/main/docs/cli.md).
+
+## Packages and support
+
+- [@flowdular/sdk](https://www.npmjs.com/package/@flowdular/sdk): shared platform APIs, UI and core modules.
+- [create-flowdular](https://www.npmjs.com/package/create-flowdular): application generator.
+- [Documentation](https://github.com/Flowdular/flowdular/tree/main/docs) · [Source and issues](https://github.com/Flowdular/flowdular) · [Website](https://flowdular.com)
 
-Release tooling can import the module distribution API from
-`flowdular/distribution`. See [Flowdular](https://github.com/Flowdular/flowdular).
+Licensed under MIT. Repository documentation and source require repository access while the repositories are private.

package/dist/distribution.js

@@ -5,7 +5,11 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __commonJS = (cb, mod) => function __require() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
 };
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
@@ -2557,10 +2561,7 @@ var project_schema_default = {
     specs: {
       type: "object",
       additionalProperties: false,
-      required: [
-        "platformRoot",
-        "moduleDirectory"
-      ],
+      required: ["platformRoot", "moduleDirectory"],
       properties: {
         platformRoot: {
           type: "string",
@@ -2575,10 +2576,7 @@ var project_schema_default = {
     modules: {
       type: "object",
       additionalProperties: false,
-      required: [
-        "roots",
-        "enabled"
-      ],
+      required: ["roots", "enabled"],
       properties: {
         roots: {
           type: "array",
@@ -2611,11 +2609,7 @@ var project_schema_default = {
     agent: {
       type: "object",
       additionalProperties: false,
-      required: [
-        "policy",
-        "blueprints",
-        "modelRouting"
-      ],
+      required: ["policy", "blueprints", "modelRouting"],
       properties: {
         policy: {
           type: "string",
@@ -2667,17 +2661,10 @@ var project_schema_default = {
                   $ref: "#/$defs/gitName"
                 },
                 provider: {
-                  enum: [
-                    "github",
-                    "none"
-                  ]
+                  enum: ["github", "none"]
                 },
                 mode: {
-                  enum: [
-                    "auto",
-                    "direct",
-                    "fork"
-                  ]
+                  enum: ["auto", "direct", "fork"]
                 },
                 forkOwner: {
                   $ref: "#/$defs/githubAccount"
@@ -2703,9 +2690,7 @@ var project_schema_default = {
     web: {
       type: "object",
       additionalProperties: false,
-      required: [
-        "mounts"
-      ],
+      required: ["mounts"],
       properties: {
         mounts: {
           type: "array",
@@ -2713,13 +2698,7 @@ var project_schema_default = {
           items: {
             type: "object",
             additionalProperties: false,
-            required: [
-              "id",
-              "moduleId",
-              "surfaceId",
-              "path",
-              "tenantId"
-            ],
+            required: ["id", "moduleId", "surfaceId", "path", "tenantId"],
             properties: {
               id: {
                 type: "string",
@@ -2754,9 +2733,7 @@ var project_schema_default = {
     application: {
       type: "object",
       additionalProperties: false,
-      required: [
-        "path"
-      ],
+      required: ["path"],
       properties: {
         path: {
           type: "string",
@@ -2770,20 +2747,21 @@ var project_schema_default = {
               "/sign-up",
               "/forgot-password",
               "/reset-password",
-              "/accept-invitation"
+              "/accept-invitation",
+              "/setup",
+              "/health",
+              "/ready",
+              "/assets"
             ]
-          }
+          },
+          maxLength: 64
         }
       }
     }
   },
   $defs: {
     deliveryTarget: {
-      enum: [
-        "workspace",
-        "git-pr",
-        "official-modules"
-      ]
+      enum: ["workspace", "git-pr", "official-modules"]
     },
     gitName: {
       type: "string",
@@ -3005,6 +2983,7 @@ var ModuleDistributionError = class extends Error {
     super(message);
     this.code = code;
   }
+  code;
 };
 function distributionAssert(condition, code, message) {
   if (!condition) throw new ModuleDistributionError(code, message);
@@ -3426,7 +3405,7 @@ import { dirname as dirname6, join as join6, relative as relative5 } from "node:
 import { createRequire } from "node:module";
 import { readFile as readFile5 } from "node:fs/promises";
 import { dirname as dirname4, join as join3 } from "node:path";
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "0.2.0";
 function npmPackage(specifier) {
   return specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : specifier.split("/")[0];
 }
@@ -4285,9 +4264,10 @@ function generateServerComposition(modules, sdk = false, mounts = [], applicatio
 	PlatformServerComposition,
 	PlatformServerContext,
 } from '${sdk ? "@flowdular/sdk/modules/auth" : "@flowdular/module-auth"}/server';
+import type { WebMount } from '${sdk ? "@flowdular/sdk/server" : "@flowdular/server"}';
 `;
   if (server.length === 0) {
-    return GENERATED_HEADER + typeImport + "\nexport function composeModuleServer(\n	_context: PlatformServerContext,\n): readonly PlatformServerComposition[] {\n	return [];\n}\n\nexport const moduleWebMounts = " + JSON.stringify(mounts) + " as const;\nexport const applicationBasePath = " + JSON.stringify(applicationPath) + ";\n";
+    return GENERATED_HEADER + typeImport + "\nexport function composeModuleServer(\n	_context: PlatformServerContext,\n): readonly PlatformServerComposition[] {\n	return [];\n}\n\nexport const moduleWebMounts: readonly WebMount[] = " + JSON.stringify(mounts) + " as const;\nexport const applicationBasePath = " + JSON.stringify(applicationPath) + ";\n";
   }
   const imports = server.map(
     (module) => platformImport(module.id, module.package, "createServerComposition")
@@ -4298,7 +4278,7 @@ function generateServerComposition(modules, sdk = false, mounts = [], applicatio
 			agentDefinitions: context.agentDefinitions.forModule('${module.id}'),
 		}), moduleId: '${module.id}' },`
   ).join("\n");
-  return GENERATED_HEADER + typeImport + imports + "\n\nexport function composeModuleServer(\n	context: PlatformServerContext,\n): readonly PlatformServerComposition[] {\n	return [\n" + calls + "\n	];\n}\n\nexport const moduleWebMounts = " + JSON.stringify(mounts) + " as const;\nexport const applicationBasePath = " + JSON.stringify(applicationPath) + ";\n";
+  return GENERATED_HEADER + typeImport + imports + "\n\nexport function composeModuleServer(\n	context: PlatformServerContext,\n): readonly PlatformServerComposition[] {\n	return [\n" + calls + "\n	];\n}\n\nexport const moduleWebMounts: readonly WebMount[] = " + JSON.stringify(mounts) + " as const;\nexport const applicationBasePath = " + JSON.stringify(applicationPath) + ";\n";
 }
 function generateClientComposition(modules, sdk = false, applicationPath = "/app") {
   const client = modules.filter((module) => module.client);
@@ -4425,7 +4405,8 @@ async function restoreSnapshots(snapshots) {
 async function syncPlatformModules(workspace, apply, enabledOverride) {
   if (workspace.config.web !== void 0 && !validators.web(workspace.config.web))
     throw new Error("Invalid web mount configuration in flowdular.json.");
-  if (workspace.config.application !== void 0 && !validators.application(workspace.config.application)) throw new Error("Invalid application path in flowdular.json.");
+  if (workspace.config.application !== void 0 && !validators.application(workspace.config.application))
+    throw new Error("Invalid application path in flowdular.json.");
   const applicationPath = workspace.config.application?.path ?? "/app";
   const enabled = enabledOverride ?? enabledModules(workspace);
   const sdk = (await sdkModules(workspace)).size > 0;
@@ -4438,7 +4419,8 @@ async function syncPlatformModules(workspace, apply, enabledOverride) {
         content: generateServerComposition(
           modules,
           sdk,
-          workspace.config.web?.mounts ?? []
+          workspace.config.web?.mounts ?? [],
+          applicationPath
         )
       },
       {

package/dist/index.js

@@ -6,7 +6,11 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __commonJS = (cb, mod) => function __require() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
 };
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
@@ -2619,10 +2623,7 @@ var project_schema_default = {
     specs: {
       type: "object",
       additionalProperties: false,
-      required: [
-        "platformRoot",
-        "moduleDirectory"
-      ],
+      required: ["platformRoot", "moduleDirectory"],
       properties: {
         platformRoot: {
           type: "string",
@@ -2637,10 +2638,7 @@ var project_schema_default = {
     modules: {
       type: "object",
       additionalProperties: false,
-      required: [
-        "roots",
-        "enabled"
-      ],
+      required: ["roots", "enabled"],
       properties: {
         roots: {
           type: "array",
@@ -2673,11 +2671,7 @@ var project_schema_default = {
     agent: {
       type: "object",
       additionalProperties: false,
-      required: [
-        "policy",
-        "blueprints",
-        "modelRouting"
-      ],
+      required: ["policy", "blueprints", "modelRouting"],
       properties: {
         policy: {
           type: "string",
@@ -2729,17 +2723,10 @@ var project_schema_default = {
                   $ref: "#/$defs/gitName"
                 },
                 provider: {
-                  enum: [
-                    "github",
-                    "none"
-                  ]
+                  enum: ["github", "none"]
                 },
                 mode: {
-                  enum: [
-                    "auto",
-                    "direct",
-                    "fork"
-                  ]
+                  enum: ["auto", "direct", "fork"]
                 },
                 forkOwner: {
                   $ref: "#/$defs/githubAccount"
@@ -2765,9 +2752,7 @@ var project_schema_default = {
     web: {
       type: "object",
       additionalProperties: false,
-      required: [
-        "mounts"
-      ],
+      required: ["mounts"],
       properties: {
         mounts: {
           type: "array",
@@ -2775,13 +2760,7 @@ var project_schema_default = {
           items: {
             type: "object",
             additionalProperties: false,
-            required: [
-              "id",
-              "moduleId",
-              "surfaceId",
-              "path",
-              "tenantId"
-            ],
+            required: ["id", "moduleId", "surfaceId", "path", "tenantId"],
             properties: {
               id: {
                 type: "string",
@@ -2816,9 +2795,7 @@ var project_schema_default = {
     application: {
       type: "object",
       additionalProperties: false,
-      required: [
-        "path"
-      ],
+      required: ["path"],
       properties: {
         path: {
           type: "string",
@@ -2832,20 +2809,21 @@ var project_schema_default = {
               "/sign-up",
               "/forgot-password",
               "/reset-password",
-              "/accept-invitation"
+              "/accept-invitation",
+              "/setup",
+              "/health",
+              "/ready",
+              "/assets"
             ]
-          }
+          },
+          maxLength: 64
         }
       }
     }
   },
   $defs: {
     deliveryTarget: {
-      enum: [
-        "workspace",
-        "git-pr",
-        "official-modules"
-      ]
+      enum: ["workspace", "git-pr", "official-modules"]
     },
     gitName: {
       type: "string",
@@ -3145,6 +3123,7 @@ var ModuleDistributionError = class extends Error {
     super(message);
     this.code = code;
   }
+  code;
 };
 function distributionAssert(condition, code, message) {
   if (!condition) throw new ModuleDistributionError(code, message);
@@ -3520,12 +3499,11 @@ import { dirname as dirname6, join as join5, relative as relative5 } from "node:
 import { createRequire } from "node:module";
 import { readFile as readFile4 } from "node:fs/promises";
 import { dirname as dirname4, join as join2 } from "node:path";
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "0.2.0";
 var LIBRARIES = /* @__PURE__ */ new Set([
   "ai-provider",
   "cli-protocol",
   "client",
-  "coding-agent",
   "contracts",
   "database",
   "database-pglite",
@@ -3533,7 +3511,6 @@ var LIBRARIES = /* @__PURE__ */ new Set([
   "dev-console",
   "harness",
   "kernel",
-  "sandbox",
   "server",
   "ui"
 ]);
@@ -4514,6 +4491,7 @@ var DatabaseError = class extends Error {
     this.code = code;
     this.name = "DatabaseError";
   }
+  code;
 };
 function assertStatement(statement) {
   if (statement.text.trim().length === 0) {
@@ -4687,6 +4665,8 @@ var DatabaseMigrationError = class extends Error {
     this.migrationId = migrationId;
     this.name = "DatabaseMigrationError";
   }
+  code;
+  migrationId;
 };
 function assertMigrationId(id) {
   if (!/^[0-9]{4}_[a-z][a-z0-9_]{0,122}$/.test(id)) {
@@ -5030,6 +5010,9 @@ var PostgresSchemaIntrospector = class {
     this.baseSignal = baseSignal;
     this.ensureActive = ensureActive;
   }
+  client;
+  baseSignal;
+  ensureActive;
   async hasTable(name, options = {}) {
     this.ensureActive();
     assertSchemaName(name);
@@ -5091,6 +5074,10 @@ var PostgresSession = class {
       ensureActive
     );
   }
+  client;
+  baseSignal;
+  ensureActive;
+  capabilities;
   adapterId = DATABASE_ADAPTER_IDS.postgresql;
   dialectId = DATABASE_DIALECT_IDS.postgresql;
   schema;
@@ -6352,9 +6339,10 @@ function generateServerComposition(modules, sdk = false, mounts = [], applicatio
 	PlatformServerComposition,
 	PlatformServerContext,
 } from '${sdk ? "@flowdular/sdk/modules/auth" : "@flowdular/module-auth"}/server';
+import type { WebMount } from '${sdk ? "@flowdular/sdk/server" : "@flowdular/server"}';
 `;
   if (server.length === 0) {
-    return GENERATED_HEADER + typeImport + "\nexport function composeModuleServer(\n	_context: PlatformServerContext,\n): readonly PlatformServerComposition[] {\n	return [];\n}\n\nexport const moduleWebMounts = " + JSON.stringify(mounts) + " as const;\nexport const applicationBasePath = " + JSON.stringify(applicationPath) + ";\n";
+    return GENERATED_HEADER + typeImport + "\nexport function composeModuleServer(\n	_context: PlatformServerContext,\n): readonly PlatformServerComposition[] {\n	return [];\n}\n\nexport const moduleWebMounts: readonly WebMount[] = " + JSON.stringify(mounts) + " as const;\nexport const applicationBasePath = " + JSON.stringify(applicationPath) + ";\n";
   }
   const imports = server.map(
     (module) => platformImport(module.id, module.package, "createServerComposition")
@@ -6365,7 +6353,7 @@ function generateServerComposition(modules, sdk = false, mounts = [], applicatio
 			agentDefinitions: context.agentDefinitions.forModule('${module.id}'),
 		}), moduleId: '${module.id}' },`
   ).join("\n");
-  return GENERATED_HEADER + typeImport + imports + "\n\nexport function composeModuleServer(\n	context: PlatformServerContext,\n): readonly PlatformServerComposition[] {\n	return [\n" + calls + "\n	];\n}\n\nexport const moduleWebMounts = " + JSON.stringify(mounts) + " as const;\nexport const applicationBasePath = " + JSON.stringify(applicationPath) + ";\n";
+  return GENERATED_HEADER + typeImport + imports + "\n\nexport function composeModuleServer(\n	context: PlatformServerContext,\n): readonly PlatformServerComposition[] {\n	return [\n" + calls + "\n	];\n}\n\nexport const moduleWebMounts: readonly WebMount[] = " + JSON.stringify(mounts) + " as const;\nexport const applicationBasePath = " + JSON.stringify(applicationPath) + ";\n";
 }
 function generateClientComposition(modules, sdk = false, applicationPath = "/app") {
   const client = modules.filter((module) => module.client);
@@ -6492,7 +6480,8 @@ async function restoreSnapshots(snapshots) {
 async function syncPlatformModules(workspace, apply, enabledOverride) {
   if (workspace.config.web !== void 0 && !validators.web(workspace.config.web))
     throw new Error("Invalid web mount configuration in flowdular.json.");
-  if (workspace.config.application !== void 0 && !validators.application(workspace.config.application)) throw new Error("Invalid application path in flowdular.json.");
+  if (workspace.config.application !== void 0 && !validators.application(workspace.config.application))
+    throw new Error("Invalid application path in flowdular.json.");
   const applicationPath = workspace.config.application?.path ?? "/app";
   const enabled = enabledOverride ?? enabledModules(workspace);
   const sdk = (await sdkModules(workspace)).size > 0;
@@ -6505,7 +6494,8 @@ async function syncPlatformModules(workspace, apply, enabledOverride) {
         content: generateServerComposition(
           modules,
           sdk,
-          workspace.config.web?.mounts ?? []
+          workspace.config.web?.mounts ?? [],
+          applicationPath
         )
       },
       {
@@ -7549,7 +7539,7 @@ function packageJson(model) {
       ...hasClient ? { "@tsrx/typescript-plugin": "0.3.120" } : {},
       "@types/node": "24.13.3",
       typescript: "5.9.3",
-      vitest: "4.1.10"
+      vitest: "4.1.11"
     }
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "flowdular",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"type": "module",
 	"bin": {
 		"flowdular": "./dist/index.js",
@@ -15,7 +15,7 @@
 		"ajv": "8.20.0",
 		"pg": "8.23.0",
 		"yaml": "2.9.0",
-		"@flowdular/sdk": "0.1.0"
+		"@flowdular/sdk": "0.2.0"
 	},
 	"license": "MIT",
 	"repository": {
@@ -26,7 +26,8 @@
 	"files": [
 		"dist",
 		"README.md",
-		"LICENSE"
+		"LICENSE",
+		"assets"
 	],
 	"publishConfig": {
 		"access": "public"