agent-scenario-loop 0.1.0

package/dist/runner/init-project.d.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+type CliArgs = {
+    'dry-run'?: string | boolean;
+    force?: string | boolean;
+    out?: string | boolean;
+    scenario?: string | boolean;
+    [key: string]: string | boolean | undefined;
+};
+type ScaffoldFile = {
+    destination: string;
+    scenarioId?: string;
+    source: string;
+    transform?: 'scenario' | 'template';
+};
+type InitProjectOptions = {
+    dryRun?: boolean;
+    force?: boolean;
+    outDir?: string;
+    packageRoot?: string;
+    scenarioId?: string;
+};
+type InitProjectResult = {
+    created: string[];
+    skipped: string[];
+    targetDir: string;
+};
+/**
+ * Prints CLI usage.
+ *
+ * @param {{write: (message: string) => unknown}} [output]
+ * @returns {void}
+ */
+declare function usage(output?: {
+    write: (message: string) => unknown;
+}): void;
+/**
+ * Parses `--key value` arguments for the init CLI.
+ *
+ * @param {string[]} argv
+ * @returns {CliArgs}
+ */
+declare function parseArgs(argv: string[]): CliArgs;
+/**
+ * Resolves the installed package root from source or built CLI execution.
+ *
+ * @returns {string}
+ */
+declare function defaultPackageRoot(): string;
+/**
+ * Normalizes a scenario id into a portable filename stem.
+ *
+ * @param {string | undefined} value
+ * @returns {string}
+ */
+declare function normalizeScenarioId(value: string | undefined): string;
+/**
+ * Builds the scaffold file map for a consuming app.
+ *
+ * @param {{packageRoot: string, scenarioId: string, targetDir: string}} options
+ * @returns {ScaffoldFile[]}
+ */
+declare function buildScaffoldFiles({ packageRoot, scenarioId, targetDir, }: {
+    packageRoot: string;
+    scenarioId: string;
+    targetDir: string;
+}): ScaffoldFile[];
+/**
+ * Scaffolds Agent Scenario Loop starter files into a consuming app directory.
+ *
+ * @param {InitProjectOptions} [options]
+ * @returns {Promise<InitProjectResult>}
+ */
+declare function initProject(options?: InitProjectOptions): Promise<InitProjectResult>;
+/**
+ * Formats init output for humans and agents.
+ *
+ * @param {InitProjectResult} result
+ * @returns {string}
+ */
+declare function formatResult(result: InitProjectResult): string;
+/**
+ * Runs the init CLI.
+ *
+ * @returns {Promise<void>}
+ */
+declare function main(): Promise<void>;
+export { buildScaffoldFiles, defaultPackageRoot, formatResult, initProject, main, normalizeScenarioId, parseArgs, usage, };
+export type { CliArgs, InitProjectOptions, InitProjectResult, ScaffoldFile, };

package/dist/runner/init-project.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildScaffoldFiles = buildScaffoldFiles;
+exports.defaultPackageRoot = defaultPackageRoot;
+exports.formatResult = formatResult;
+exports.initProject = initProject;
+exports.main = main;
+exports.normalizeScenarioId = normalizeScenarioId;
+exports.parseArgs = parseArgs;
+exports.usage = usage;
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const { hasHelpFlag, writeUsage } = require('./cli');
+const TEMPLATE_FILES = {
+    config: 'project.config.json',
+    evidenceProvider: 'evidence-provider.json',
+    gitignoreSnippet: 'gitignore-snippet',
+    integrationReadme: 'integration-readme.md',
+    packageScripts: 'package-scripts.json',
+    primaryRunner: 'primary-runner.json',
+    accessibilityProviderScript: path.join('scripts', 'asl-capture-accessibility-provider.mjs'),
+    profilerProviderScript: path.join('scripts', 'asl-capture-profiler-provider.mjs'),
+    scenario: 'mobile-scenario.json',
+};
+/**
+ * Prints CLI usage.
+ *
+ * @param {{write: (message: string) => unknown}} [output]
+ * @returns {void}
+ */
+function usage(output = process.stderr) {
+    writeUsage([
+        'Usage: asl-init [--out <dir>] [--scenario <id>] [--force] [--dry-run]',
+        '',
+        'Copies public Agent Scenario Loop templates into a consuming app layout.',
+        'Refuses to overwrite existing files unless --force is provided.',
+    ], output);
+}
+/**
+ * Parses `--key value` arguments for the init CLI.
+ *
+ * @param {string[]} argv
+ * @returns {CliArgs}
+ */
+function parseArgs(argv) {
+    const args = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === '--') {
+            continue;
+        }
+        if (!token || !token.startsWith('--')) {
+            continue;
+        }
+        const key = token.slice(2);
+        const value = argv[index + 1];
+        if (value && !value.startsWith('--')) {
+            args[key] = value;
+            index += 1;
+        }
+        else {
+            args[key] = true;
+        }
+    }
+    return args;
+}
+/**
+ * Resolves the installed package root from source or built CLI execution.
+ *
+ * @returns {string}
+ */
+function defaultPackageRoot() {
+    return path.resolve(__dirname, '..', '..');
+}
+/**
+ * Returns true when a boolean-style CLI value is enabled.
+ *
+ * @param {string | boolean | undefined} value
+ * @returns {boolean}
+ */
+function isEnabled(value) {
+    return value === true || value === 'true';
+}
+/**
+ * Normalizes a scenario id into a portable filename stem.
+ *
+ * @param {string | undefined} value
+ * @returns {string}
+ */
+function normalizeScenarioId(value) {
+    const normalized = (value || 'first-journey')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, '-')
+        .replace(/^-+|-+$/gu, '');
+    return normalized || 'first-journey';
+}
+/**
+ * Builds the scaffold file map for a consuming app.
+ *
+ * @param {{packageRoot: string, scenarioId: string, targetDir: string}} options
+ * @returns {ScaffoldFile[]}
+ */
+function buildScaffoldFiles({ packageRoot, scenarioId, targetDir, }) {
+    const templatesRoot = path.join(packageRoot, 'templates');
+    return [
+        {
+            source: path.join(templatesRoot, TEMPLATE_FILES.config),
+            destination: path.join(targetDir, 'asl.config.json'),
+        },
+        {
+            source: path.join(templatesRoot, TEMPLATE_FILES.scenario),
+            destination: path.join(targetDir, 'scenarios', 'mobile', `${scenarioId}.json`),
+            scenarioId,
+            transform: 'scenario',
+        },
+        {
+            source: path.join(templatesRoot, TEMPLATE_FILES.primaryRunner),
+            destination: path.join(targetDir, 'runner-manifests', 'primary-runner.json'),
+        },
+        {
+            source: path.join(templatesRoot, TEMPLATE_FILES.evidenceProvider),
+            destination: path.join(targetDir, 'runner-manifests', 'evidence-provider.json'),
+        },
+        {
+            source: path.join(templatesRoot, TEMPLATE_FILES.accessibilityProviderScript),
+            destination: path.join(targetDir, 'scripts', 'asl-capture-accessibility-provider.mjs'),
+        },
+        {
+            source: path.join(templatesRoot, TEMPLATE_FILES.profilerProviderScript),
+            destination: path.join(targetDir, 'scripts', 'asl-capture-profiler-provider.mjs'),
+        },
+        {
+            source: path.join(templatesRoot, TEMPLATE_FILES.integrationReadme),
+            destination: path.join(targetDir, 'asl', 'README.md'),
+            scenarioId,
+            transform: 'template',
+        },
+        {
+            source: path.join(templatesRoot, TEMPLATE_FILES.packageScripts),
+            destination: path.join(targetDir, 'asl', 'package-scripts.json'),
+            scenarioId,
+            transform: 'template',
+        },
+        {
+            source: path.join(templatesRoot, TEMPLATE_FILES.gitignoreSnippet),
+            destination: path.join(targetDir, 'asl', 'gitignore-snippet'),
+        },
+        {
+            source: path.join(packageRoot, 'app', 'profile-session.ts'),
+            destination: path.join(targetDir, 'src', 'devtools', 'profile-session.ts'),
+        },
+    ];
+}
+/**
+ * Copies one scaffold template unless it already exists and overwrite is disabled.
+ * Scenario templates get their stable id fields aligned with the requested filename.
+ *
+ * @param {{dryRun: boolean, file: ScaffoldFile, force: boolean}} options
+ * @returns {Promise<'created' | 'skipped'>}
+ */
+async function copyScaffoldFile({ dryRun, file, force, }) {
+    if (fs.existsSync(file.destination) && !force) {
+        return 'skipped';
+    }
+    if (dryRun) {
+        return 'created';
+    }
+    await fsp.mkdir(path.dirname(file.destination), { recursive: true });
+    if (file.transform === 'scenario' && file.scenarioId) {
+        const scenario = JSON.parse(await fsp.readFile(file.source, 'utf8'));
+        scenario.id = file.scenarioId;
+        scenario.flowId = file.scenarioId;
+        await fsp.writeFile(file.destination, `${JSON.stringify(scenario, null, 2)}\n`, 'utf8');
+    }
+    else if (file.transform === 'template' && file.scenarioId) {
+        const template = await fsp.readFile(file.source, 'utf8');
+        await fsp.writeFile(file.destination, template.replace(/\{\{SCENARIO_ID\}\}/gu, file.scenarioId), 'utf8');
+    }
+    else {
+        await fsp.copyFile(file.source, file.destination);
+    }
+    return 'created';
+}
+/**
+ * Scaffolds Agent Scenario Loop starter files into a consuming app directory.
+ *
+ * @param {InitProjectOptions} [options]
+ * @returns {Promise<InitProjectResult>}
+ */
+async function initProject(options = {}) {
+    const packageRoot = options.packageRoot ?? defaultPackageRoot();
+    const targetDir = path.resolve(options.outDir ?? process.cwd());
+    const scenarioId = normalizeScenarioId(options.scenarioId);
+    const files = buildScaffoldFiles({ packageRoot, scenarioId, targetDir });
+    const created = [];
+    const skipped = [];
+    for (const file of files) {
+        const result = await copyScaffoldFile({
+            dryRun: Boolean(options.dryRun),
+            file,
+            force: Boolean(options.force),
+        });
+        const relativeDestination = path.relative(targetDir, file.destination).split(path.sep).join('/');
+        if (result === 'created') {
+            created.push(relativeDestination);
+        }
+        else {
+            skipped.push(relativeDestination);
+        }
+    }
+    return {
+        created,
+        skipped,
+        targetDir,
+    };
+}
+/**
+ * Formats init output for humans and agents.
+ *
+ * @param {InitProjectResult} result
+ * @returns {string}
+ */
+function formatResult(result) {
+    const lines = [
+        `Agent Scenario Loop files initialized in ${result.targetDir}`,
+    ];
+    if (result.created.length > 0) {
+        lines.push('created:', ...result.created.map((filePath) => `- ${filePath}`));
+    }
+    if (result.skipped.length > 0) {
+        lines.push('skipped:', ...result.skipped.map((filePath) => `- ${filePath}`));
+    }
+    return lines.join('\n');
+}
+/**
+ * Runs the init CLI.
+ *
+ * @returns {Promise<void>}
+ */
+async function main() {
+    const argv = process.argv.slice(2);
+    if (hasHelpFlag(argv)) {
+        usage(process.stdout);
+        return;
+    }
+    const args = parseArgs(argv);
+    const result = await initProject({
+        dryRun: isEnabled(args['dry-run']),
+        force: isEnabled(args.force),
+        ...(typeof args.out === 'string' ? { outDir: args.out } : {}),
+        ...(typeof args.scenario === 'string' ? { scenarioId: args.scenario } : {}),
+    });
+    process.stdout.write(`${formatResult(result)}\n`);
+}
+if (require.main === module) {
+    main().catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    });
+}

package/dist/runner/ios-simctl-driver.d.ts

@@ -0,0 +1,69 @@
+type IosSimctlCommandResult = {
+    action: string;
+    args: string[];
+    command: string;
+    exitCode: number;
+    rawFileName: string;
+    stderr: string;
+    stdout: string;
+};
+type IosSimctlCommandExecutor = (command: string, args: string[]) => Promise<{
+    args: string[];
+    command: string;
+    exitCode: number;
+    stderr: string;
+    stdout: string;
+}>;
+type IosSimctlDriverOptions = {
+    deviceUdid: string;
+    executor: IosSimctlCommandExecutor;
+    xcrunPath: string;
+};
+type IosSimctlDeepLinkOptions = {
+    rawFileName?: string;
+    url: string;
+};
+type IosSimctlReadLogsOptions = {
+    last?: string;
+    predicate?: string;
+    rawFileName?: string;
+};
+type IosSimctlScreenshotOptions = {
+    display?: string;
+    imageType?: string;
+    mask?: string;
+    outputPath: string;
+    rawFileName?: string;
+};
+type IosSimctlDriver = {
+    appInfo: (bundleId: string) => Promise<IosSimctlCommandResult>;
+    launchBundle: (bundleId: string) => Promise<IosSimctlCommandResult>;
+    openDeepLink: (options: IosSimctlDeepLinkOptions) => Promise<IosSimctlCommandResult>;
+    readLogs: (options?: IosSimctlReadLogsOptions) => Promise<IosSimctlCommandResult>;
+    screenshot: (options: IosSimctlScreenshotOptions) => Promise<IosSimctlCommandResult>;
+    terminateBundle: (bundleId: string) => Promise<IosSimctlCommandResult>;
+};
+declare const PROFILE_LOG_PREDICATE = "eventMessage CONTAINS \"[profile-event]\" OR eventMessage CONTAINS \"[profile-session]\"";
+/**
+ * Combines stdout and stderr into the raw evidence text written by callers.
+ *
+ * @param {{stdout: string, stderr: string}} result
+ * @returns {string}
+ */
+declare function formatIosSimctlRawOutput(result: {
+    stdout: string;
+    stderr: string;
+}): string;
+/**
+ * Creates a small simctl-backed iOS driver for lifecycle helpers and evidence capture.
+ *
+ * The generic driver capabilities exposed here are `readLogs` and `screenshot`.
+ * Launching bundles, terminating bundles, and opening deep links remain
+ * lifecycle helpers used by built-in runners.
+ *
+ * @param {IosSimctlDriverOptions} options
+ * @returns {IosSimctlDriver}
+ */
+declare function createIosSimctlDriver({ deviceUdid, executor, xcrunPath, }: IosSimctlDriverOptions): IosSimctlDriver;
+export { PROFILE_LOG_PREDICATE, createIosSimctlDriver, formatIosSimctlRawOutput, };
+export type { IosSimctlCommandExecutor, IosSimctlCommandResult, IosSimctlDeepLinkOptions, IosSimctlDriver, IosSimctlDriverOptions, IosSimctlReadLogsOptions, IosSimctlScreenshotOptions, };

package/dist/runner/ios-simctl-driver.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROFILE_LOG_PREDICATE = void 0;
+exports.createIosSimctlDriver = createIosSimctlDriver;
+exports.formatIosSimctlRawOutput = formatIosSimctlRawOutput;
+const PROFILE_LOG_PREDICATE = 'eventMessage CONTAINS "[profile-event]" OR eventMessage CONTAINS "[profile-session]"';
+exports.PROFILE_LOG_PREDICATE = PROFILE_LOG_PREDICATE;
+/**
+ * Adds stable driver metadata to one simctl command result.
+ *
+ * @param {{action: string, rawFileName: string, result: Awaited<ReturnType<IosSimctlCommandExecutor>>}} options
+ * @returns {IosSimctlCommandResult}
+ */
+function buildDriverResult({ action, rawFileName, result, }) {
+    return {
+        action,
+        args: result.args,
+        command: result.command,
+        exitCode: result.exitCode,
+        rawFileName,
+        stderr: result.stderr,
+        stdout: result.stdout,
+    };
+}
+/**
+ * Combines stdout and stderr into the raw evidence text written by callers.
+ *
+ * @param {{stdout: string, stderr: string}} result
+ * @returns {string}
+ */
+function formatIosSimctlRawOutput(result) {
+    return [result.stdout, result.stderr].filter(Boolean).join('\n');
+}
+/**
+ * Creates a small simctl-backed iOS driver for lifecycle helpers and evidence capture.
+ *
+ * The generic driver capabilities exposed here are `readLogs` and `screenshot`.
+ * Launching bundles, terminating bundles, and opening deep links remain
+ * lifecycle helpers used by built-in runners.
+ *
+ * @param {IosSimctlDriverOptions} options
+ * @returns {IosSimctlDriver}
+ */
+function createIosSimctlDriver({ deviceUdid, executor, xcrunPath, }) {
+    return {
+        async appInfo(bundleId) {
+            const rawFileName = 'ios-app-info.txt';
+            const result = await executor(xcrunPath, ['simctl', 'appinfo', deviceUdid, bundleId]);
+            return buildDriverResult({ action: 'appInfo', rawFileName, result });
+        },
+        async launchBundle(bundleId) {
+            const rawFileName = 'ios-launch.txt';
+            const result = await executor(xcrunPath, ['simctl', 'launch', deviceUdid, bundleId]);
+            return buildDriverResult({ action: 'launchBundle', rawFileName, result });
+        },
+        async openDeepLink({ rawFileName = 'ios-deep-link.txt', url, }) {
+            const result = await executor(xcrunPath, ['simctl', 'openurl', deviceUdid, url]);
+            return buildDriverResult({ action: 'openDeepLink', rawFileName, result });
+        },
+        async readLogs({ last = '2m', predicate = PROFILE_LOG_PREDICATE, rawFileName = 'ios-simctl-log.txt', } = {}) {
+            const result = await executor(xcrunPath, [
+                'simctl',
+                'spawn',
+                deviceUdid,
+                'log',
+                'show',
+                '--style',
+                'compact',
+                '--last',
+                last,
+                '--predicate',
+                predicate,
+            ]);
+            return buildDriverResult({ action: 'readLogs', rawFileName, result });
+        },
+        async screenshot({ display, imageType, mask, outputPath, rawFileName = 'ios-screenshot.txt', }) {
+            const args = ['simctl', 'io', deviceUdid, 'screenshot'];
+            if (imageType) {
+                args.push(`--type=${imageType}`);
+            }
+            if (display) {
+                args.push(`--display=${display}`);
+            }
+            if (mask) {
+                args.push(`--mask=${mask}`);
+            }
+            args.push(outputPath);
+            const result = await executor(xcrunPath, args);
+            return buildDriverResult({ action: 'screenshot', rawFileName, result });
+        },
+        async terminateBundle(bundleId) {
+            const rawFileName = 'ios-terminate.txt';
+            const result = await executor(xcrunPath, ['simctl', 'terminate', deviceUdid, bundleId]);
+            return buildDriverResult({ action: 'terminateBundle', rawFileName, result });
+        },
+    };
+}