@axm.sh/cli 0.0.1

package/dist/src/resolution/resolvers/url.js

@@ -0,0 +1,79 @@
+/**
+ * URL resolver for unmatched URL-like inputs.
+ *
+ * Handles GitHub/GitLab HTTPS URLs, SSH URLs, and other HTTP URLs
+ * that weren't caught by earlier resolvers.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { resolveSource } from "../../sources/index.js";
+import { buildOriginUrl } from "./url-utils.js";
+/**
+ * URL pattern for detecting URL-like inputs.
+ * Matches: https://, http://, git@
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+const URL_PATTERN = /^(?:https?:\/\/|git@)/;
+/**
+ * Check if input looks like a URL.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+const looksLikeUrl = (input) => {
+    return URL_PATTERN.test(input);
+};
+/**
+ * Resolve URL-like inputs to ExtensionRefs.
+ *
+ * Handles:
+ * - GitHub HTTPS URLs: `https://github.com/owner/repo`
+ * - GitLab HTTPS URLs: `https://gitlab.com/owner/repo`
+ * - GitHub SSH URLs: `git@github.com:owner/repo.git`
+ * - GitLab SSH URLs: `git@gitlab.com:owner/repo.git`
+ *
+ * This is the last resolver in the pipeline - catches any URL-like inputs
+ * that weren't handled by earlier resolvers.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @param input - The input string to resolve
+ * @param _options - Resolution options (unused currently)
+ * @returns Effect containing array of ExtensionRefs, or empty array if not a match
+ */
+export const resolveUrl = (input) => {
+    const trimmed = input.trim();
+    // Return empty array if input doesn't look like a URL
+    if (!looksLikeUrl(trimmed)) {
+        return Effect.succeed([]);
+    }
+    // Use resolveSource for the heavy lifting
+    return resolveSource(trimmed).pipe(Effect.map((src) => {
+        // Handle github/gitlab sources
+        if (src.type === "github" || src.type === "gitlab") {
+            const ref = {
+                type: "skill", // Infer as skill for now (will be enhanced later with manifest fetch)
+                source: src.type,
+                origin: buildOriginUrl(src.type, src.owner, src.repo),
+                originalInput: input,
+                name: Option.none(),
+                ref: src.ref,
+                path: src.subPath,
+                metadata: {
+                    version: Option.none(),
+                    description: Option.none(),
+                    files: Option.none(),
+                    versionConstraint: Option.none(),
+                },
+            };
+            return [ref];
+        }
+        // Other source types (bitbucket, git, registry) not yet supported by URL resolver
+        return [];
+    }), 
+    // On parse error, return empty array (not a match for this resolver)
+    Effect.catchAll(() => Effect.succeed([])));
+};
+//# sourceMappingURL=url.js.map

package/dist/src/resolution/resolvers/url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../../../../src/resolution/resolvers/url.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,GAAG,uBAAuB,CAAC;AAE5C;;;;GAIG;AACH,MAAM,YAAY,GAAG,CAAC,KAAa,EAAW,EAAE;IAC9C,OAAO,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACjC,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAa,EAAE,EAAE;IAC1C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAE7B,sDAAsD;IACtD,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,OAAO,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,0CAA0C;IAC1C,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC,IAAI,CAChC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACjB,+BAA+B;QAC/B,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACnD,MAAM,GAAG,GAAiB;gBACxB,IAAI,EAAE,OAAO,EAAE,sEAAsE;gBACrF,MAAM,EAAE,GAAG,CAAC,IAAI;gBAChB,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC;gBACrD,aAAa,EAAE,KAAK;gBACpB,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE;gBACnB,GAAG,EAAE,GAAG,CAAC,GAAG;gBACZ,IAAI,EAAE,GAAG,CAAC,OAAO;gBACjB,QAAQ,EAAE;oBACR,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE;oBACtB,WAAW,EAAE,MAAM,CAAC,IAAI,EAAE;oBAC1B,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE;oBACpB,iBAAiB,EAAE,MAAM,CAAC,IAAI,EAAE;iBACjC;aACF,CAAC;YAEF,OAAO,CAAC,GAAG,CAAC,CAAC;QACf,CAAC;QAED,kFAAkF;QAClF,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC;IACF,qEAAqE;IACrE,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAC1C,CAAC;AACJ,CAAC,CAAC"}

package/dist/src/resolution/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Extension resolution types.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { Option } from "effect";
+import type { SourceType } from "../sources/index.js";
+/**
+ * Discriminator for extension kinds.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type ExtensionType = "skill" | "command" | "pack" | "mcp-server";
+/**
+ * Additional info about the extension.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface ExtensionMetadata {
+    /** Resolved version of the extension */
+    readonly version: Option.Option<string>;
+    /** Human-readable description */
+    readonly description: Option.Option<string>;
+    /** List of files included in the extension */
+    readonly files: Option.Option<readonly string[]>;
+    /** Version constraint from the original input */
+    readonly versionConstraint: Option.Option<string>;
+}
+/**
+ * The result of resolution - a fully resolved extension reference.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface ExtensionRef {
+    /** The kind of extension */
+    readonly type: ExtensionType;
+    /** Where the extension comes from */
+    readonly source: SourceType;
+    /** Fully resolved URL or path */
+    readonly origin: string;
+    /** Git ref if applicable (branch, tag, commit) */
+    readonly ref: Option.Option<string>;
+    /** Scoped name if resolved (e.g., @scope/name) */
+    readonly name: Option.Option<string>;
+    /** Subpath within repo */
+    readonly path: Option.Option<string>;
+    /** Original input string preserved for debugging */
+    readonly originalInput: string;
+    /** Additional metadata about the extension */
+    readonly metadata: ExtensionMetadata;
+}
+/**
+ * Configuration options for resolution.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface ResolutionOptions {
+    /** Filter by extension types */
+    readonly types: Option.Option<readonly ExtensionType[]>;
+    /** Filter by source types */
+    readonly sources: Option.Option<readonly SourceType[]>;
+    /** Filter by agent names */
+    readonly agents: Option.Option<readonly string[]>;
+    /** Current working directory */
+    readonly cwd: Option.Option<string>;
+    /** Implied scope from settings */
+    readonly scope: Option.Option<string>;
+    /** Project .axm directory location */
+    readonly projectDir: Option.Option<string>;
+    /** Global ~/.axm directory location */
+    readonly globalDir: Option.Option<string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/resolution/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/resolution/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAErC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,YAAY,CAAC;AAExE;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACxC,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;IACjD,iDAAiD;IACjD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;CACnD;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACpC,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACrC,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACrC,oDAAoD;IACpD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC;IACxD,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,UAAU,EAAE,CAAC,CAAC;IACvD,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;IAClD,gCAAgC;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACpC,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACtC,sCAAsC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3C,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;CAC3C"}

package/dist/src/resolution/types.js

@@ -0,0 +1,8 @@
+/**
+ * Extension resolution types.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/resolution/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/resolution/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/src/runtime/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * CLI Runtime Module
+ *
+ * Provides centralized Effect runtime configuration for CLI commands.
+ * Uses ManagedRuntime for proper lifecycle management and resource cleanup.
+ */
+import type { HttpClient } from "@effect/platform";
+import * as NodeContext from "@effect/platform-node/NodeContext";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as ManagedRuntime from "effect/ManagedRuntime";
+import type * as Scope from "effect/Scope";
+import { type Log, type Spinner, type Note, type TextInput, type PasswordInput, type Confirm, type Select, type Multiselect } from "../tui/index.js";
+import { type SourceProviders } from "../sources/index.js";
+import { Workspace, type WorkspaceContextOptions } from "../workspace/index.js";
+/**
+ * Standard dependencies available to all CLI commands:
+ * - FileSystem, Path (from @effect/platform-node)
+ * - HttpClient (for network requests)
+ * - TUI services (interactive prompts, logging, spinners)
+ */
+export type AppLayer = NodeContext.NodeContext | HttpClient.HttpClient | Log | Spinner | Note | TextInput | PasswordInput | Confirm | Select | Multiselect;
+/**
+ * Layer providing all standard CLI dependencies.
+ */
+export declare const AppLayer: Layer.Layer<AppLayer>;
+/**
+ * ManagedRuntime for CLI commands.
+ * Handles lifecycle and resource cleanup automatically.
+ */
+export declare const Runtime: ManagedRuntime.ManagedRuntime<AppLayer, never>;
+/**
+ * Run an Effect program with CLI dependencies and error handling.
+ * Exits process with code 1 on failure.
+ *
+ * When workspace options are provided, the WorkspaceContext layer is
+ * composed into the runtime so handlers can yield WorkspaceContextTag
+ * directly.
+ */
+export declare function run<A, E>(program: Effect.Effect<A, E, AppLayer>): Promise<A>;
+export declare function run<A, E>(program: Effect.Effect<A, E, AppLayer | Workspace | SourceProviders | Scope.Scope>, options: {
+    readonly workspace: WorkspaceContextOptions;
+}): Promise<A>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,WAAW,MAAM,mCAAmC,CAAC;AACjE,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,cAAc,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAE3C,OAAO,EAEL,KAAK,GAAG,EACR,KAAK,OAAO,EACZ,KAAK,IAAI,EACT,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,OAAO,EACZ,KAAK,MAAM,EACX,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,KAAK,eAAe,EAAuB,MAAM,qBAAqB,CAAC;AAChF,OAAO,EACL,SAAS,EAET,KAAK,uBAAuB,EAC7B,MAAM,uBAAuB,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAChB,WAAW,CAAC,WAAW,GACvB,UAAU,CAAC,UAAU,GACrB,GAAG,GACH,OAAO,GACP,IAAI,GACJ,SAAS,GACT,aAAa,GACb,OAAO,GACP,MAAM,GACN,WAAW,CAAC;AAEhB;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,QAAQ,CAI1C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,OAAO,gDAAgC,CAAC;AAErD;;;;;;;GAOG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAC9E,wBAAgB,GAAG,CAAC,CAAC,EAAE,CAAC,EACtB,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,eAAe,GAAG,KAAK,CAAC,KAAK,CAAC,EAClF,OAAO,EAAE;IAAE,QAAQ,CAAC,SAAS,EAAE,uBAAuB,CAAA;CAAE,GACvD,OAAO,CAAC,CAAC,CAAC,CAAC"}

package/dist/src/runtime/index.js

@@ -0,0 +1,37 @@
+/**
+ * CLI Runtime Module
+ *
+ * Provides centralized Effect runtime configuration for CLI commands.
+ * Uses ManagedRuntime for proper lifecycle management and resource cleanup.
+ */
+import * as FetchHttpClient from "@effect/platform/FetchHttpClient";
+import * as NodeContext from "@effect/platform-node/NodeContext";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as ManagedRuntime from "effect/ManagedRuntime";
+import { TuiLive, } from "../tui/index.js";
+import { SourceProvidersLive } from "../sources/index.js";
+import { Workspace, layer as workspaceLayer, } from "../workspace/index.js";
+/**
+ * Layer providing all standard CLI dependencies.
+ */
+export const AppLayer = Layer.mergeAll(NodeContext.layer, FetchHttpClient.layer, TuiLive);
+/**
+ * ManagedRuntime for CLI commands.
+ * Handles lifecycle and resource cleanup automatically.
+ */
+export const Runtime = ManagedRuntime.make(AppLayer);
+export function run(program, options) {
+    const provided = options?.workspace
+        ? (() => {
+            const wsLayer = workspaceLayer(options.workspace);
+            const sourceProvidersLayer = Layer.provide(SourceProvidersLive, wsLayer);
+            return program.pipe(Effect.provide(Layer.mergeAll(wsLayer, sourceProvidersLayer)), Effect.scoped);
+        })()
+        : program;
+    return provided.pipe(Effect.catchAll((error) => Effect.sync(() => {
+        console.error(error);
+        process.exit(1);
+    })), Runtime.runPromise);
+}
+//# sourceMappingURL=index.js.map

package/dist/src/runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,eAAe,MAAM,kCAAkC,CAAC;AACpE,OAAO,KAAK,WAAW,MAAM,mCAAmC,CAAC;AACjE,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,cAAc,MAAM,uBAAuB,CAAC;AAGxD,OAAO,EACL,OAAO,GASR,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAwB,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,EACL,SAAS,EACT,KAAK,IAAI,cAAc,GAExB,MAAM,uBAAuB,CAAC;AAoB/B;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAA0B,KAAK,CAAC,QAAQ,CAC3D,WAAW,CAAC,KAAK,EACjB,eAAe,CAAC,KAAK,EACrB,OAAO,CACR,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AAerD,MAAM,UAAU,GAAG,CACjB,OAAkF,EAClF,OAAyD;IAEzD,MAAM,QAAQ,GAAG,OAAO,EAAE,SAAS;QACjC,CAAC,CAAC,CAAC,GAAG,EAAE;YACJ,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAClD,MAAM,oBAAoB,GAAG,KAAK,CAAC,OAAO,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAAC;YACzE,OAAO,OAAO,CAAC,IAAI,CACjB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC,EAC7D,MAAM,CAAC,MAAM,CACd,CAAC;QACJ,CAAC,CAAC,EAAE;QACN,CAAC,CAAE,OAAyC,CAAC;IAE/C,OAAO,QAAQ,CAAC,IAAI,CAClB,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,EAAE,CACxB,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;QACf,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CACH,EACD,OAAO,CAAC,UAAU,CACnB,CAAC;AACJ,CAAC"}

package/dist/src/settings/format-preserving-json.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Format-preserving JSON modification utilities.
+ *
+ * Detects and preserves existing formatting (indentation, line endings)
+ * when modifying JSON files using jsonc-parser's surgical edit operations.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as FileSystem from "@effect/platform/FileSystem";
+import * as Effect from "effect/Effect";
+import type { FormattingOptions } from "jsonc-parser";
+import { SettingsWriteError } from "./settings.js";
+/**
+ * Detected formatting options including EOL style.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface DetectedFormatting extends FormattingOptions {
+    readonly eol: string;
+}
+/**
+ * Detect formatting (indentation and line endings) from existing JSON text.
+ *
+ * Scans for the first indented line to determine tab vs space indentation
+ * and tab size. Detects CRLF vs LF line endings.
+ *
+ * Falls back to 2-space indentation with LF line endings.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const detectFormatting: (text: string) => DetectedFormatting;
+/**
+ * Ensure a top-level property exists in JSON text without reformatting siblings.
+ *
+ * `jsonc-parser`'s `modify` rewrites all sibling content when inserting a new
+ * top-level property, which can reformat compact arrays into multi-line. This
+ * function inserts the property by direct text manipulation, leaving all
+ * existing content byte-for-byte identical.
+ *
+ * Returns the text unchanged if the property already exists.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const ensureTopLevelProperty: (text: string, key: string, defaultValue: unknown, formatting: DetectedFormatting, keyOrder?: ReadonlyArray<string>) => string;
+/**
+ * A single JSON modification: set or remove a value at a path.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface JsonModification {
+    readonly path: ReadonlyArray<string | number>;
+    readonly value: unknown;
+}
+/**
+ * Read a JSON file, apply surgical modifications preserving formatting, and write back.
+ *
+ * Each modification targets a JSON path and sets (or removes via `undefined`) a value.
+ * Modifications are applied sequentially since each edit may shift offsets.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const modifyJsonFile: (filePath: string, modifications: ReadonlyArray<JsonModification>) => Effect.Effect<void, SettingsWriteError, FileSystem.FileSystem>;
+//# sourceMappingURL=format-preserving-json.d.ts.map

package/dist/src/settings/format-preserving-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-preserving-json.d.ts","sourceRoot":"","sources":["../../../src/settings/format-preserving-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,UAAU,MAAM,6BAA6B,CAAC;AAC1D,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAMnD;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,kBAmB/C,CAAC;AAMF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,GACjC,MAAM,MAAM,EACZ,KAAK,MAAM,EACX,cAAc,OAAO,EACrB,YAAY,kBAAkB,EAC9B,WAAW,aAAa,CAAC,MAAM,CAAC,KAC/B,MA+CF,CAAC;AAMF;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,EAAE,eAAe,aAAa,CAAC,gBAAgB,CAAC,mEAoC3F,CAAC"}

package/dist/src/settings/format-preserving-json.js

@@ -0,0 +1,132 @@
+/**
+ * Format-preserving JSON modification utilities.
+ *
+ * Detects and preserves existing formatting (indentation, line endings)
+ * when modifying JSON files using jsonc-parser's surgical edit operations.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as FileSystem from "@effect/platform/FileSystem";
+import * as Effect from "effect/Effect";
+import { applyEdits, findNodeAtLocation, modify, parseTree } from "jsonc-parser";
+import { SettingsWriteError } from "./settings.js";
+/**
+ * Detect formatting (indentation and line endings) from existing JSON text.
+ *
+ * Scans for the first indented line to determine tab vs space indentation
+ * and tab size. Detects CRLF vs LF line endings.
+ *
+ * Falls back to 2-space indentation with LF line endings.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const detectFormatting = (text) => {
+    // Detect EOL: if \r\n appears, use CRLF, else LF
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    // Detect indentation: find first line that starts with whitespace
+    const lines = text.split(/\r?\n/);
+    for (const line of lines) {
+        const match = line.match(/^(\s+)/);
+        if (match) {
+            const indent = match[1];
+            if (indent.startsWith("\t")) {
+                return { tabSize: 1, insertSpaces: false, eol };
+            }
+            return { tabSize: indent.length, insertSpaces: true, eol };
+        }
+    }
+    // Default: 2-space, LF
+    return { tabSize: 2, insertSpaces: true, eol };
+};
+// -----------------------------------------------------------------------------
+// Surgical Property Insertion
+// -----------------------------------------------------------------------------
+/**
+ * Ensure a top-level property exists in JSON text without reformatting siblings.
+ *
+ * `jsonc-parser`'s `modify` rewrites all sibling content when inserting a new
+ * top-level property, which can reformat compact arrays into multi-line. This
+ * function inserts the property by direct text manipulation, leaving all
+ * existing content byte-for-byte identical.
+ *
+ * Returns the text unchanged if the property already exists.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const ensureTopLevelProperty = (text, key, defaultValue, formatting, keyOrder) => {
+    const tree = parseTree(text);
+    if (!tree || tree.type !== "object")
+        return text;
+    // Already exists — no-op
+    if (findNodeAtLocation(tree, [key]))
+        return text;
+    const indent = formatting.insertSpaces ? " ".repeat(formatting.tabSize ?? 2) : "\t";
+    const serialized = JSON.stringify(defaultValue);
+    const newEntry = `${indent}"${key}": ${serialized}`;
+    // When keyOrder is provided, try to insert at the correct position
+    if (keyOrder && tree.children && tree.children.length > 0) {
+        const keyIndex = keyOrder.indexOf(key);
+        if (keyIndex !== -1) {
+            // Find the first existing property that comes after `key` in the schema order
+            for (const child of tree.children) {
+                const childKey = child.children?.[0]?.value;
+                if (!childKey)
+                    continue;
+                const childIndex = keyOrder.indexOf(childKey);
+                if (childIndex > keyIndex) {
+                    // Insert before this child's line
+                    const childOffset = child.offset;
+                    // Find the start of the line containing this property
+                    let lineStart = childOffset;
+                    while (lineStart > 0 && text[lineStart - 1] !== "\n") {
+                        lineStart--;
+                    }
+                    const before = text.substring(0, lineStart);
+                    const after = text.substring(lineStart);
+                    return `${before}${newEntry},${formatting.eol}${after}`;
+                }
+            }
+        }
+    }
+    // Fall back: append at the end (before closing brace)
+    const closingBrace = text.lastIndexOf("}");
+    if (closingBrace === -1)
+        return text;
+    const hasProperties = (tree.children?.length ?? 0) > 0;
+    const before = text.substring(0, closingBrace).trimEnd();
+    const comma = hasProperties ? "," : "";
+    const after = text.substring(closingBrace);
+    return `${before}${comma}${formatting.eol}${newEntry}${formatting.eol}${after.trimStart()}`;
+};
+/**
+ * Read a JSON file, apply surgical modifications preserving formatting, and write back.
+ *
+ * Each modification targets a JSON path and sets (or removes via `undefined`) a value.
+ * Modifications are applied sequentially since each edit may shift offsets.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const modifyJsonFile = (filePath, modifications) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    // Read raw text
+    let text = yield* fs.readFileString(filePath).pipe(Effect.mapError((error) => new SettingsWriteError({
+        path: filePath,
+        message: `Failed to read file for modification: ${filePath}`,
+        cause: error,
+    })));
+    // Detect formatting from existing content
+    const formatting = detectFormatting(text);
+    // Apply each modification sequentially (each edit may shift offsets)
+    for (const mod of modifications) {
+        const edits = modify(text, [...mod.path], mod.value, { formattingOptions: formatting });
+        text = applyEdits(text, edits);
+    }
+    // Write back
+    yield* fs.writeFileString(filePath, text).pipe(Effect.mapError((error) => new SettingsWriteError({
+        path: filePath,
+        message: `Failed to write modified file: ${filePath}`,
+        cause: error,
+    })));
+});
+//# sourceMappingURL=format-preserving-json.js.map

package/dist/src/settings/format-preserving-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-preserving-json.js","sourceRoot":"","sources":["../../../src/settings/format-preserving-json.ts"],"names":[],"mappings":"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"}

package/dist/src/settings/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Settings feature module.
+ *
+ * Provides settings schema definitions and I/O functions for managing
+ * the `.axm/settings.json` configuration file.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+export type { ExtensionMap, Settings, SkillsMap, SourceConfig } from "./schema.js";
+export { ExtensionMapSchema, SETTINGS_KEY_ORDER, SettingsSchema, SkillsMapSchema, SourceConfigSchema, } from "./schema.js";
+export type { SettingsError } from "./settings.js";
+export { createDefaultSettings, DEFAULT_SCOPE, orderSettingsKeys, readSettings, SETTINGS_FILENAME, SettingsNotFoundError, SettingsParseError, SettingsWriteError, writeSettings, } from "./settings.js";
+export type { DetectedFormatting, JsonModification } from "./format-preserving-json.js";
+export { detectFormatting, ensureTopLevelProperty, modifyJsonFile, } from "./format-preserving-json.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/settings/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/settings/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAGrB,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AAGvB,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACxF,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,cAAc,GACf,MAAM,6BAA6B,CAAC"}

package/dist/src/settings/index.js

@@ -0,0 +1,13 @@
+/**
+ * Settings feature module.
+ *
+ * Provides settings schema definitions and I/O functions for managing
+ * the `.axm/settings.json` configuration file.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+export { ExtensionMapSchema, SETTINGS_KEY_ORDER, SettingsSchema, SkillsMapSchema, SourceConfigSchema, } from "./schema.js";
+export { createDefaultSettings, DEFAULT_SCOPE, orderSettingsKeys, readSettings, SETTINGS_FILENAME, SettingsNotFoundError, SettingsParseError, SettingsWriteError, writeSettings, } from "./settings.js";
+export { detectFormatting, ensureTopLevelProperty, modifyJsonFile, } from "./format-preserving-json.js";
+//# sourceMappingURL=index.js.map

package/dist/src/settings/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/settings/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAIrB,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AAIvB,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,cAAc,GACf,MAAM,6BAA6B,CAAC"}