fix(#804): reject unknown installer arguments

packages/mosaic/framework/defaults/README.md

@@ -177,6 +177,8 @@ bash tools/install.sh --cli         # npm CLI only (skip framework)
 bash tools/install.sh --ref v1.0    # Install from a specific git ref
 ```
 
+The installer rejects unrecognized flags or positional arguments before making changes and prints the supported-option usage.
+
 ## Universal Skills
 
 The installer syncs skills from `mosaic/agent-skills` into `~/.config/mosaic/skills/`, then links each skill into runtime directories.

packages/mosaic/src/commands/install-arguments.spec.ts

@@ -8,34 +8,54 @@ import { describe, expect, it } from 'vitest';
 
 const INSTALLER_PATH = fileURLToPath(new URL('../../../../tools/install.sh', import.meta.url));
 
+async function runInstaller(args: string[]): Promise<{
+  status: number | null;
+  stderr: string;
+  npmCalled: boolean;
+}> {
+  const home = await mkdtemp(join(tmpdir(), 'mosaic-installer-args-'));
+  const bin = join(home, 'bin');
+  const npmMarker = join(home, 'npm-called');
+
+  try {
+    await mkdir(bin);
+    const npmShim = join(bin, 'npm');
+    await writeFile(npmShim, `#!/bin/sh\n: > "${npmMarker}"\n`);
+    await chmod(npmShim, 0o755);
+
+    const result = spawnSync('bash', [INSTALLER_PATH, ...args], {
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        HOME: home,
+        MOSAIC_NO_COLOR: '1',
+        PATH: `${bin}:${process.env.PATH ?? ''}`,
+      },
+    });
+
+    return {
+      status: result.status,
+      stderr: result.stderr,
+      npmCalled: existsSync(npmMarker),
+    };
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+}
+
+function expectUnknownArgument(result: Awaited<ReturnType<typeof runInstaller>>): void {
+  expect(result.status).not.toBe(0);
+  expect(result.stderr).toContain('Unknown argument: --bogus');
+  expect(result.stderr).toMatch(/Usage: .*install\.sh/);
+  expect(result.npmCalled).toBe(false);
+}
+
 describe('installer arguments', () => {
   it('rejects an unknown argument before installation starts', async () => {
-    const home = await mkdtemp(join(tmpdir(), 'mosaic-installer-args-'));
-    const bin = join(home, 'bin');
-    const npmMarker = join(home, 'npm-called');
+    expectUnknownArgument(await runInstaller(['--cli', '--bogus']));
+  });
 
-    try {
-      await mkdir(bin);
-      const npmShim = join(bin, 'npm');
-      await writeFile(npmShim, `#!/bin/sh\n: > "${npmMarker}"\n`);
-      await chmod(npmShim, 0o755);
-
-      const result = spawnSync('bash', [INSTALLER_PATH, '--cli', '--bogus'], {
-        encoding: 'utf8',
-        env: {
-          ...process.env,
-          HOME: home,
-          MOSAIC_NO_COLOR: '1',
-          PATH: `${bin}:${process.env.PATH ?? ''}`,
-        },
-      });
-
-      expect(result.status).not.toBe(0);
-      expect(result.stderr).toContain('Unknown argument: --bogus');
-      expect(result.stderr).toMatch(/Usage: .*install\.sh/);
-      expect(existsSync(npmMarker)).toBe(false);
-    } finally {
-      await rm(home, { recursive: true, force: true });
-    }
+  it('does not let --ref consume an unknown option', async () => {
+    expectUnknownArgument(await runInstaller(['--cli', '--ref', '--bogus']));
   });
 });