@nagarjuna2002/ios-agent 0.2.0

package/dist/config.js

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import path from "node:path";
+import { LAYOUT_VERSION } from "./layout.js";
+export const CONFIG_VERSION = 1;
+export function defaultConfig(name, appPath, now = new Date()) {
+    return {
+        layoutVersion: LAYOUT_VERSION,
+        configVersion: CONFIG_VERSION,
+        name,
+        createdAt: now.toISOString(),
+        apps: [{ name, path: toPosix(appPath), platforms: ["iOS"] }],
+        plugins: [],
+    };
+}
+export function writeConfig(layout, config) {
+    fs.mkdirSync(layout.internal, { recursive: true });
+    fs.writeFileSync(layout.config, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+export class ConfigError extends Error {
+}
+/**
+ * Read and validate the config.
+ *
+ * Throws with the offending file named rather than returning a partial object:
+ * a config that is present but malformed is a different problem from one that
+ * is missing, and collapsing the two sends people looking in the wrong place.
+ */
+export function readConfig(layout) {
+    let raw;
+    try {
+        raw = fs.readFileSync(layout.config, "utf8");
+    }
+    catch {
+        throw new ConfigError(`No config at ${layout.config}. Run \`ios-agent init\` in this project.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new ConfigError(`${layout.config} is not valid JSON: ${error.message}`);
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        throw new ConfigError(`${layout.config} must contain a JSON object.`);
+    }
+    const candidate = parsed;
+    if (typeof candidate.name !== "string" || candidate.name.length === 0) {
+        throw new ConfigError(`${layout.config} is missing a "name".`);
+    }
+    if (!Array.isArray(candidate.apps)) {
+        throw new ConfigError(`${layout.config} is missing an "apps" array.`);
+    }
+    const layoutVersion = typeof candidate.layoutVersion === "number" ? candidate.layoutVersion : 0;
+    if (layoutVersion > LAYOUT_VERSION) {
+        throw new ConfigError(`${layout.config} was written by a newer ios-agent (layout ${layoutVersion}, this build understands ${LAYOUT_VERSION}). Upgrade rather than letting an old build rewrite it.`);
+    }
+    return {
+        layoutVersion,
+        configVersion: typeof candidate.configVersion === "number" ? candidate.configVersion : 0,
+        name: candidate.name,
+        createdAt: typeof candidate.createdAt === "string" ? candidate.createdAt : "",
+        apps: candidate.apps.filter(isAppEntry).map((app) => ({ ...app, path: toPosix(app.path) })),
+        plugins: Array.isArray(candidate.plugins) ? candidate.plugins.filter((p) => typeof p === "string") : [],
+    };
+}
+function isAppEntry(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const entry = value;
+    return typeof entry.name === "string" && typeof entry.path === "string";
+}
+/**
+ * Store paths POSIX-style regardless of the platform that wrote them.
+ *
+ * A Windows-authored config carrying `App\MyApp` is unreadable on the macOS
+ * machine that builds the app — and this file is tracked, so it crosses
+ * machines by design.
+ */
+export function toPosix(value) {
+    return value.split(path.sep).join("/");
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/discover.d.ts

@@ -0,0 +1,21 @@
+import { ProjectLayout } from "./layout.js";
+export interface Discovery {
+    readonly layout: ProjectLayout;
+    /** How the root was determined — surfaced by `where`, because an implicit root is unfalsifiable. */
+    readonly source: "explicit" | "environment" | "ancestor";
+}
+/**
+ * Find the project root for a working directory.
+ *
+ * Resolution order, highest first:
+ *   1. an explicit path the caller passed
+ *   2. `IOS_AGENT_HOME`
+ *   3. the nearest ancestor containing `.ios-agent/`
+ *
+ * The upward walk is what git, npm, and cargo all do, and it is why `ios-agent`
+ * works from a nested source directory instead of only from the root. Returning
+ * `source` alongside the path matters as much as the path: a user staring at an
+ * empty result cannot otherwise tell an empty project from a wrong root, which
+ * is the single most confusing failure this class of tool has.
+ */
+export declare function discoverProject(startDir?: string, env?: NodeJS.ProcessEnv, explicitRoot?: string): Discovery | undefined;

package/dist/discover.js

@@ -0,0 +1,48 @@
+import fs from "node:fs";
+import path from "node:path";
+import { INTERNAL_DIR, layoutFor } from "./layout.js";
+/** How far up the tree to look before giving up. Guards against a symlink loop. */
+const MAX_ASCENT = 64;
+/**
+ * Find the project root for a working directory.
+ *
+ * Resolution order, highest first:
+ *   1. an explicit path the caller passed
+ *   2. `IOS_AGENT_HOME`
+ *   3. the nearest ancestor containing `.ios-agent/`
+ *
+ * The upward walk is what git, npm, and cargo all do, and it is why `ios-agent`
+ * works from a nested source directory instead of only from the root. Returning
+ * `source` alongside the path matters as much as the path: a user staring at an
+ * empty result cannot otherwise tell an empty project from a wrong root, which
+ * is the single most confusing failure this class of tool has.
+ */
+export function discoverProject(startDir = process.cwd(), env = process.env, explicitRoot) {
+    if (explicitRoot) {
+        return { layout: layoutFor(explicitRoot), source: "explicit" };
+    }
+    const fromEnv = env.IOS_AGENT_HOME?.trim();
+    if (fromEnv) {
+        return { layout: layoutFor(fromEnv), source: "environment" };
+    }
+    let current = path.resolve(startDir);
+    for (let step = 0; step < MAX_ASCENT; step += 1) {
+        if (isDirectory(path.join(current, INTERNAL_DIR))) {
+            return { layout: layoutFor(current), source: "ancestor" };
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return undefined;
+}
+function isDirectory(candidate) {
+    try {
+        return fs.statSync(candidate).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=discover.js.map

package/dist/discover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.js","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,YAAY,EAAiB,SAAS,EAAE,MAAM,aAAa,CAAC;AAErE,mFAAmF;AACnF,MAAM,UAAU,GAAG,EAAE,CAAC;AAQtB;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAC7B,WAAmB,OAAO,CAAC,GAAG,EAAE,EAChC,MAAyB,OAAO,CAAC,GAAG,EACpC,YAAqB;IAErB,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IACjE,CAAC;IAED,MAAM,OAAO,GAAG,GAAG,CAAC,cAAc,EAAE,IAAI,EAAE,CAAC;IAC3C,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IAC/D,CAAC;IAED,IAAI,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACrC,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,UAAU,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC;YAClD,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;QAC5D,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,MAAM,KAAK,OAAO;YAAE,MAAM;QAC9B,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,WAAW,CAAC,SAAiB;IACpC,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from "./commands.js";
+process.exitCode = run(process.argv.slice(2));
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAEpC,OAAO,CAAC,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/layout.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The one place the internal directory is named.
+ *
+ * Every other module derives from this table. A string literal ".ios-agent"
+ * anywhere else in the codebase is a bug: it is how a rename half-lands and the
+ * CLI starts writing to one directory while the MCP server reads another.
+ */
+export declare const INTERNAL_DIR = ".ios-agent";
+/** The user-facing source directory. The only thing they should need to open. */
+export declare const APP_DIR = "App";
+/** Bumped when the on-disk shape changes incompatibly. Stored in config.json. */
+export declare const LAYOUT_VERSION = 1;
+export type EntryKind = "file" | "directory";
+export interface InternalEntry {
+    readonly name: string;
+    readonly kind: EntryKind;
+    /**
+     * Whether the entry belongs in version control.
+     *
+     * This single flag drives two things that must never disagree: the generated
+     * `.ios-agent/.gitignore`, and what `ios-agent clean` is allowed to delete.
+     * Deriving both from one declaration is why `clean` can be non-interactive —
+     * it provably cannot remove something a human authored.
+     */
+    readonly tracked: boolean;
+    readonly purpose: string;
+    /** Created eagerly on scaffold, or lazily on first use. */
+    readonly eager: boolean;
+}
+/**
+ * Everything the tool owns, and nothing the user does.
+ *
+ * Adding a future feature — plugins, simulator state, build artifacts — is one
+ * row here. It then appears in the gitignore, in `clean`, in `doctor`, and in
+ * `where --json` with no further edits. That is the scalability requirement
+ * expressed as code rather than as a convention people have to remember.
+ */
+export declare const INTERNAL_ENTRIES: readonly InternalEntry[];
+export interface ProjectLayout {
+    /** Directory containing `App/` and `.ios-agent/`. */
+    readonly root: string;
+    readonly app: string;
+    readonly internal: string;
+    readonly config: string;
+    readonly state: string;
+    readonly metadata: string;
+    readonly cache: string;
+    readonly logs: string;
+    readonly build: string;
+    readonly screenshots: string;
+    readonly templates: string;
+    readonly plugins: string;
+    readonly tmp: string;
+    readonly gitignore: string;
+}
+/**
+ * Absolute paths for one project root.
+ *
+ * Pure — it touches no filesystem, so it is the same on every platform and
+ * trivially testable. Creation is a separate, explicit step.
+ */
+export declare function layoutFor(root: string): ProjectLayout;
+/**
+ * The contents of `.ios-agent/.gitignore`, generated from `INTERNAL_ENTRIES`.
+ *
+ * Ignore-everything-then-unignore keeps the rules inside the directory they
+ * govern, so the project's root `.gitignore` stays about the project. It also
+ * means a future disposable directory is ignored the moment it is declared —
+ * the common failure being a new cache directory that nobody remembers to add,
+ * and which then shows up in someone's pull request.
+ */
+export declare function gitignoreContents(): string;
+/** Entries `clean` may delete: exactly those not under version control. */
+export declare function disposableEntries(): readonly InternalEntry[];
+/**
+ * Where caches shared across every project go.
+ *
+ * Per-project caches that hold downloaded templates or SDK metadata make a
+ * fresh clone slow and duplicate hundreds of megabytes per project — the reason
+ * npm, Cargo, and pub all keep one user-level store. Each platform has its own
+ * documented location and none of them is `~/.ios-agent`.
+ */
+/**
+ * `platform` and `home` are parameters so tests can exercise all three branches
+ * on one machine. They do NOT make the result platform-independent: `path` uses
+ * the **host's** rules throughout, so asking for the linux branch on Windows
+ * returns a Windows-shaped string. Production never does that — the defaults
+ * are the host — but a test that hardcodes an expected string will pass on
+ * Linux and fail on Windows.
+ *
+ * Concretely: `path.resolve("/xdg")` yields `/xdg` on Linux and `D:\xdg` on a
+ * Windows runner, because resolve anchors a drive-less path to the current
+ * drive. Expectations must therefore be built with the same call this function
+ * makes, not with a literal.
+ */
+export declare function globalCacheDir(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, home?: string): string;

package/dist/layout.js

@@ -0,0 +1,184 @@
+import path from "node:path";
+import os from "node:os";
+/**
+ * The one place the internal directory is named.
+ *
+ * Every other module derives from this table. A string literal ".ios-agent"
+ * anywhere else in the codebase is a bug: it is how a rename half-lands and the
+ * CLI starts writing to one directory while the MCP server reads another.
+ */
+export const INTERNAL_DIR = ".ios-agent";
+/** The user-facing source directory. The only thing they should need to open. */
+export const APP_DIR = "App";
+/** Bumped when the on-disk shape changes incompatibly. Stored in config.json. */
+export const LAYOUT_VERSION = 1;
+/**
+ * Everything the tool owns, and nothing the user does.
+ *
+ * Adding a future feature — plugins, simulator state, build artifacts — is one
+ * row here. It then appears in the gitignore, in `clean`, in `doctor`, and in
+ * `where --json` with no further edits. That is the scalability requirement
+ * expressed as code rather than as a convention people have to remember.
+ */
+export const INTERNAL_ENTRIES = [
+    {
+        name: "config.json",
+        kind: "file",
+        tracked: true,
+        eager: true,
+        purpose: "Project identity and settings. The only tracked file here — it describes the project, so it belongs in review.",
+    },
+    {
+        name: "state.json",
+        kind: "file",
+        tracked: false,
+        eager: false,
+        purpose: "Mutable runtime state: last simulator, last build, session scratch. Machine-local by definition.",
+    },
+    {
+        name: "metadata.json",
+        kind: "file",
+        tracked: false,
+        eager: false,
+        purpose: "Facts derived by scanning the project. Always reproducible, never authored.",
+    },
+    {
+        name: "cache",
+        kind: "directory",
+        tracked: false,
+        eager: false,
+        purpose: "Project-derived cache. Anything shared across projects belongs in the global cache instead.",
+    },
+    {
+        name: "logs",
+        kind: "directory",
+        tracked: false,
+        eager: false,
+        purpose: "Command and build logs, newest last.",
+    },
+    {
+        name: "build",
+        kind: "directory",
+        tracked: false,
+        eager: false,
+        purpose: "Derived build artifacts. Deleting this must never lose work.",
+    },
+    {
+        name: "screenshots",
+        kind: "directory",
+        tracked: false,
+        eager: false,
+        purpose: "Simulator captures from automated runs.",
+    },
+    {
+        name: "templates",
+        kind: "directory",
+        tracked: true,
+        eager: false,
+        purpose: "Project-local template overrides. Tracked, because an override is a decision the team made.",
+    },
+    {
+        name: "plugins",
+        kind: "directory",
+        tracked: true,
+        eager: false,
+        purpose: "Plugin manifests. Tracked so a checkout reproduces the toolchain; downloaded plugin code lives in the global cache.",
+    },
+    {
+        name: "tmp",
+        kind: "directory",
+        tracked: false,
+        eager: false,
+        purpose: "Scratch space for in-flight commands. Safe to delete at any moment.",
+    },
+];
+/**
+ * Absolute paths for one project root.
+ *
+ * Pure — it touches no filesystem, so it is the same on every platform and
+ * trivially testable. Creation is a separate, explicit step.
+ */
+export function layoutFor(root) {
+    const absoluteRoot = path.resolve(root);
+    const internal = path.join(absoluteRoot, INTERNAL_DIR);
+    const inside = (name) => path.join(internal, name);
+    return {
+        root: absoluteRoot,
+        app: path.join(absoluteRoot, APP_DIR),
+        internal,
+        config: inside("config.json"),
+        state: inside("state.json"),
+        metadata: inside("metadata.json"),
+        cache: inside("cache"),
+        logs: inside("logs"),
+        build: inside("build"),
+        screenshots: inside("screenshots"),
+        templates: inside("templates"),
+        plugins: inside("plugins"),
+        tmp: inside("tmp"),
+        gitignore: inside(".gitignore"),
+    };
+}
+/**
+ * The contents of `.ios-agent/.gitignore`, generated from `INTERNAL_ENTRIES`.
+ *
+ * Ignore-everything-then-unignore keeps the rules inside the directory they
+ * govern, so the project's root `.gitignore` stays about the project. It also
+ * means a future disposable directory is ignored the moment it is declared —
+ * the common failure being a new cache directory that nobody remembers to add,
+ * and which then shows up in someone's pull request.
+ */
+export function gitignoreContents() {
+    const tracked = INTERNAL_ENTRIES.filter((entry) => entry.tracked);
+    const lines = [
+        "# Generated by ios-agent. Edits are overwritten.",
+        "#",
+        "# Everything the tool writes is disposable and machine-local; the few",
+        "# entries below describe the project itself and belong in review.",
+        "*",
+        "!.gitignore",
+        ...tracked.map((entry) => (entry.kind === "directory" ? `!${entry.name}/` : `!${entry.name}`)),
+        "",
+    ];
+    return lines.join("\n");
+}
+/** Entries `clean` may delete: exactly those not under version control. */
+export function disposableEntries() {
+    return INTERNAL_ENTRIES.filter((entry) => !entry.tracked);
+}
+/**
+ * Where caches shared across every project go.
+ *
+ * Per-project caches that hold downloaded templates or SDK metadata make a
+ * fresh clone slow and duplicate hundreds of megabytes per project — the reason
+ * npm, Cargo, and pub all keep one user-level store. Each platform has its own
+ * documented location and none of them is `~/.ios-agent`.
+ */
+/**
+ * `platform` and `home` are parameters so tests can exercise all three branches
+ * on one machine. They do NOT make the result platform-independent: `path` uses
+ * the **host's** rules throughout, so asking for the linux branch on Windows
+ * returns a Windows-shaped string. Production never does that — the defaults
+ * are the host — but a test that hardcodes an expected string will pass on
+ * Linux and fail on Windows.
+ *
+ * Concretely: `path.resolve("/xdg")` yields `/xdg` on Linux and `D:\xdg` on a
+ * Windows runner, because resolve anchors a drive-less path to the current
+ * drive. Expectations must therefore be built with the same call this function
+ * makes, not with a literal.
+ */
+export function globalCacheDir(env = process.env, platform = process.platform, home = os.homedir()) {
+    const override = env.IOS_AGENT_CACHE_DIR?.trim();
+    if (override)
+        return path.resolve(override);
+    if (platform === "win32") {
+        const base = env.LOCALAPPDATA?.trim() || path.join(home, "AppData", "Local");
+        return path.join(base, "ios-agent", "Cache");
+    }
+    if (platform === "darwin") {
+        return path.join(home, "Library", "Caches", "ios-agent");
+    }
+    const xdg = env.XDG_CACHE_HOME?.trim();
+    return path.join(xdg ? path.resolve(xdg) : path.join(home, ".cache"), "ios-agent");
+}
+//# sourceMappingURL=layout.js.map

package/dist/layout.js.map

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

package/dist/scaffold.d.ts

@@ -0,0 +1,42 @@
+import { ProjectLayout } from "./layout.js";
+export declare class ScaffoldError extends Error {
+}
+/**
+ * Validate a project name before any directory exists.
+ *
+ * Stricter than the filesystem on purpose. The name becomes a Swift type
+ * prefix, a directory, and a target name, so the intersection of what all three
+ * accept is what is actually usable — and a name rejected up front costs
+ * nothing, while one rejected by Xcode two steps later costs a rebuild.
+ */
+export declare function validateProjectName(name: string): void;
+export interface ScaffoldOptions {
+    readonly name: string;
+    /** Parent directory. The project is created at `<parentDir>/<name>`. */
+    readonly parentDir: string;
+    /** Create only `App/`; `.ios-agent/` materialises on first command that needs it. */
+    readonly minimal?: boolean;
+    readonly license?: "MIT" | "none";
+    /** Allow scaffolding into a directory that already has contents. */
+    readonly force?: boolean;
+    readonly now?: Date;
+    readonly brief?: string;
+    readonly xcodegen?: boolean;
+}
+export interface ScaffoldResult {
+    readonly layout: ProjectLayout;
+    /** Absolute paths written, in creation order. */
+    readonly created: string[];
+}
+export declare function scaffoldProject(options: ScaffoldOptions): ScaffoldResult;
+/**
+ * Create `.ios-agent/` and the entries marked eager, idempotently.
+ *
+ * Every command that writes calls this first, which is what makes the minimal
+ * scaffold honest: `MyApp/App/` alone is a real project, and the internal
+ * directory appears the first time there is something to put in it rather than
+ * sitting empty as a promise.
+ */
+export declare function ensureInternal(layout: ProjectLayout): string[];
+/** Create one internal directory on demand. Callers name it via the layout. */
+export declare function ensureInternalDir(layout: ProjectLayout, target: string): string;