@astrale-os/sdk 0.5.0-beta.71 → 0.5.0-beta.73

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.5.0-beta.73](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.72...sdk-v0.5.0-beta.73) (2026-08-28)
+
+
+### Bug Fixes
+
+* **adapter-astrale:** discover official CLI installation ([#320](https://github.com/astrale-os/sdk/issues/320)) ([aa5ade5](https://github.com/astrale-os/sdk/commit/aa5ade5e7d861b2b3e037ae84ca14a36fef48fb2))
+* add command-specific astrale-domain help ([#318](https://github.com/astrale-os/sdk/issues/318)) ([4956a77](https://github.com/astrale-os/sdk/commit/4956a77337c70659fa45102bed84e4feab39aad1))
+
+## [0.5.0-beta.72](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.71...sdk-v0.5.0-beta.72) (2026-08-28)
+
+
+### Bug Fixes
+
+* **linter:** recognize nested schema modules ([#316](https://github.com/astrale-os/sdk/issues/316)) ([d9ad841](https://github.com/astrale-os/sdk/commit/d9ad84165103ed7741f11801ea740476109b99b3))
+
 ## [0.5.0-beta.71](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.70...sdk-v0.5.0-beta.71) (2026-08-28)
 
 

package/dist/tooling/cli/arguments.d.ts

@@ -1,6 +1,8 @@
 import type { LintReportFormat } from '../linter/index.js';
+export declare const COMMANDS: readonly ['dev', 'build', 'deploy', 'lint', 'package'];
+export type Command = (typeof COMMANDS)[number];
 export interface ParsedArgs {
-    readonly command: 'dev' | 'build' | 'deploy' | 'lint' | 'package';
+    readonly command: Command;
     readonly env: string;
     readonly fix?: boolean;
     readonly format?: LintReportFormat;

package/dist/tooling/cli/arguments.js

@@ -1,4 +1,5 @@
 import { isIP } from 'node:net';
+export const COMMANDS = ['dev', 'build', 'deploy', 'lint', 'package'];
 /** Parse the frozen `astrale-domain` command grammar without performing effects. */
 export function parseArgs(argv) {
     const [command, ...rest] = argv;

package/dist/tooling/cli/help.d.ts

@@ -0,0 +1,8 @@
+import { type Command } from './arguments.js';
+export interface HelpRequest {
+    readonly command?: Command;
+}
+/** Resolve help without parsing a project or performing any command effects. */
+export declare function helpRequest(argv: readonly string[]): HelpRequest | undefined;
+export declare function helpText(command?: Command): string;
+export declare const ERROR_USAGE = "Usage: astrale-domain <command> [options]\nRun \"astrale-domain --help\" for available commands.\n";

package/dist/tooling/cli/help.js

@@ -0,0 +1,117 @@
+import { COMMANDS } from './arguments.js';
+/** Resolve help without parsing a project or performing any command effects. */
+export function helpRequest(argv) {
+    if (!argv.some((argument) => argument === '--help' || argument === '-h'))
+        return undefined;
+    const command = COMMANDS.find((candidate) => candidate === argv[0]);
+    return command === undefined ? Object.freeze({}) : Object.freeze({ command });
+}
+export function helpText(command) {
+    return command === undefined ? GLOBAL_HELP : COMMAND_HELP[command];
+}
+export const ERROR_USAGE = `Usage: astrale-domain <command> [options]
+Run "astrale-domain --help" for available commands.
+`;
+const GLOBAL_HELP = `Build, develop, deploy, lint, and package Astrale Domains.
+
+Usage:
+  astrale-domain <command> [options]
+
+Commands:
+  dev [environment]       Build and run a watched development session.
+  build                   Build and verify without deploying.
+  deploy <environment>    Deploy through the configured adapter.
+  lint                    Check Domain source and architecture.
+  package                 Prepare public declarations for publication.
+
+Options:
+  -h, --help              Show help.
+
+Run "astrale-domain <command> --help" for command-specific help.
+`;
+const COMMAND_HELP = Object.freeze({
+    dev: `Build, verify, and run a watched Domain development session.
+
+Usage:
+  astrale-domain dev [environment] [options]
+
+Arguments:
+  environment             Adapter environment key (default: dev).
+
+Options:
+  --environment <name>    Select the environment without a positional argument.
+  --port <port>           Use a strict local Worker port (default: OS-allocated).
+  --host <url>            Use an externally managed public origin; requires a strict port
+                          from --port or adapter configuration.
+  -h, --help              Show help for dev.
+
+Behavior:
+  Builds and verifies the Application, Runtime, and adapter-prepared artifact.
+  Serves the generated Worker and an optional Vite frontend. Vite uses its own
+  OS-allocated loopback port.
+  Watches imported authored sources and declared secrets. Configuration changes
+  require restarting the command.
+
+Adapters:
+  cloudflare              Runs the local Worker and optional Vite frontend only;
+                          it owns no public ingress or Kernel installation.
+  astrale                 Also owns a Quick Tunnel when no public host is configured,
+                          reconciles each verified Release on the configured or
+                          CLI-active instance, and starts a local View host when
+                          a View is declared. The installation remains after the
+                          development session stops.
+`,
+    build: `Build and verify a Domain without deploying it.
+
+Usage:
+  astrale-domain build
+
+Options:
+  -h, --help              Show help for build.
+
+Behavior:
+  Compiles the Application and Runtime, runs adapter preparation, and verifies
+  the resulting artifact. It does not load declared secrets, deploy, or install
+  the Domain.
+`,
+    deploy: `Build, verify, and deploy a Domain through its configured adapter.
+
+Usage:
+  astrale-domain deploy <environment>
+  astrale-domain deploy --environment <name>
+
+Arguments:
+  environment             Required adapter environment key.
+
+Options:
+  --environment <name>    Select the environment without a positional argument.
+  -h, --help              Show help for deploy.
+
+Behavior:
+  Builds and verifies the Release, loads declared secrets, and invokes the
+  adapter deployment. Deployment does not install the deployed Domain on a
+  Kernel instance.
+`,
+    lint: `Check Domain source and architecture.
+
+Usage:
+  astrale-domain lint [options]
+
+Options:
+  --fix                   Apply supported fixes.
+  --format <format>       Select stylish or json output (default: stylish).
+  -h, --help              Show help for lint.
+`,
+    package: `Prepare public TypeScript declarations for package publication.
+
+Usage:
+  astrale-domain package
+
+Options:
+  -h, --help              Show help for package.
+
+Behavior:
+  Normalizes public declaration references in the current package. This command
+  does not load astrale.config.ts and does not require Bun.
+`,
+});

package/dist/tooling/cli/orchestrate.js

@@ -7,11 +7,13 @@ import { parseArgs } from './arguments.js';
 import { BunRequiredError } from './bun.js';
 import { develop } from './development/develop.js';
 import { loadDeclaredSecrets } from './dotenv.js';
+import { ERROR_USAGE, helpRequest, helpText } from './help.js';
 import { error, info } from './log.js';
 const CONFIG_NAMES = ['astrale.config.ts', 'astrale.config.js', 'astrale.config.mjs'];
 export async function run(argv) {
-    if (argv.includes('--help') || argv.includes('-h')) {
-        usage();
+    const requestedHelp = helpRequest(argv);
+    if (requestedHelp !== undefined) {
+        process.stdout.write(helpText(requestedHelp.command));
         return 0;
     }
     let parsed;
@@ -153,5 +155,5 @@ function deploymentLifecycle() {
 function usage(message) {
     if (message !== undefined)
         error(message);
-    process.stderr.write('Usage: astrale-domain <dev|build|deploy|lint|package> [environment]\n');
+    process.stderr.write(ERROR_USAGE);
 }

package/dist/tooling/linter/adapters/typescript/discover.js

@@ -206,7 +206,7 @@ async function admitFile(root, absolutePath, policy) {
     const source = ts.createSourceFile(absolutePath, text, ts.ScriptTarget.Latest, true, scriptKind(absolutePath));
     const layer = policy.layers.find(({ sourcePath }) => path.startsWith(sourcePath));
     const remainder = layer ? path.slice(layer.sourcePath.length) : undefined;
-    const first = remainder?.split('/')[0];
+    const submodule = semanticSubmodule(layer?.id, remainder);
     const role = sourceRole(path, layer?.id);
     return Object.freeze({
         absolutePath,
@@ -215,11 +215,23 @@ async function admitFile(root, absolutePath, policy) {
         source,
         role,
         ...(layer ? { layer: layer.id } : {}),
-        ...(first && remainder?.includes('/') && first !== '__tests__' ? { submodule: first } : {}),
+        ...(submodule ? { submodule } : {}),
         imports: Object.freeze(collectImports(source)),
         dependencyIssues: Object.freeze(collectDependencyIssues(source)),
     });
 }
+function semanticSubmodule(layer, remainder) {
+    if (!remainder)
+        return undefined;
+    const segments = remainder.split('/');
+    const first = segments[0];
+    if (!first || first === '__tests__' || segments.length < 2)
+        return undefined;
+    if (layer === 'schema' && first === 'modules' && segments.length >= 3 && segments[1]) {
+        return `modules/${segments[1]}`;
+    }
+    return first;
+}
 function sourceRole(path, layer) {
     const segments = path.split('/');
     if (segments.includes('__tests__') || /\.(?:test|spec|bench|perf)\.[cm]?[jt]sx?$/.test(path)) {

package/dist/tooling/linter/implementations/source/global.js

@@ -335,16 +335,24 @@ export const globalRules = [
             const evidence = [];
             for (const file of production(project)) {
                 for (const sourceImport of file.imports) {
-                    const localDeepImport = sourceImport.specifier.match(/^#([^/]+)\/[^/]+\/.+/);
-                    if (localDeepImport &&
-                        project.policy.layers.some(({ id }) => id === localDeepImport[1])) {
+                    const target = resolveProjectImport(project, file, sourceImport.specifier);
+                    const localAliasSegments = sourceImport.specifier.startsWith('#')
+                        ? sourceImport.specifier.split('/')
+                        : [];
+                    const aliasLayer = localAliasSegments[0]?.slice(1);
+                    const nestedSchemaModuleFacade = aliasLayer === 'schema' &&
+                        localAliasSegments[1] === 'modules' &&
+                        localAliasSegments.length === 3;
+                    if (!target &&
+                        localAliasSegments.length >= 3 &&
+                        !nestedSchemaModuleFacade &&
+                        project.policy.layers.some(({ id }) => id === aliasLayer)) {
                         evidence.push(violation(file, sourceImport.node, `Import ${sourceImport.specifier} reaches private source; use the semantic submodule facade.`));
                     }
                     if (isForeignDomain(sourceImport.specifier) &&
                         isDeepPackageImport(sourceImport.specifier)) {
                         evidence.push(violation(file, sourceImport.node, `Foreign Domain import ${sourceImport.specifier} bypasses ${packageRoot(sourceImport.specifier)}.`));
                     }
-                    const target = resolveProjectImport(project, file, sourceImport.specifier);
                     if (!file.layer ||
                         !target?.layer ||
                         file.layer !== target.layer ||

package/dist/tooling/linter/implementations/source/tests.js

@@ -10,12 +10,16 @@ export const testRules = [
                 if (file.layer && file.layer !== 'tests' && file.submodule) {
                     const sourcePath = project.policy.layers.find(({ id }) => id === file.layer)?.sourcePath;
                     if (sourcePath !== undefined) {
-                        owners.set(`${file.layer}/${file.submodule}`, { file, sourcePath });
+                        owners.set(`${file.layer}\0${file.submodule}`, {
+                            file,
+                            layer: file.layer,
+                            sourcePath,
+                            submodule: file.submodule,
+                        });
                     }
                 }
             }
-            for (const [owner, { file, sourcePath }] of owners) {
-                const [layer, submodule] = owner.split('/');
+            for (const { file, layer, sourcePath, submodule } of owners.values()) {
                 const physicalOwner = `${sourcePath}${submodule}`;
                 const hasFocusedEvidence = project.files.some((candidate) => candidate.layer === layer &&
                     candidate.submodule === submodule &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/sdk",
-  "version": "0.5.0-beta.71",
+  "version": "0.5.0-beta.73",
   "description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
   "keywords": [
     "astrale",