cmd-shim 7.0.0

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/cmd-shim@7.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/cmd-shim@7.0.0

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:0ecebf683c6be88ef39d2b88cdb26deeb2bbf34adbb7993887949e449138d548","contract":["cmdShim(from, to) creates POSIX sh, Windows .cmd, and PowerShell .ps1 shim files with mode 0o755","cmdShim parses shebang lines including /usr/bin/env -S environment variables and arguments into sh, .cmd (@SET), and .ps1 shims","cmdShim(from, to) rejects with ENOENT when the source script does not exist","cmdShim.ifExists(from, to) resolves without creating shim files when the source script does not exist and creates shims when it does"],"goal":"verify pkg:npm/cmd-shim@7.0.0","kind":"HOW","packages":["pkg:npm/cmd-shim@7.0.0"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/cmd-shim@7.0.0"],"schemaVersion":1,"subject":"pkg:npm/cmd-shim@7.0.0","verifierAdapter":"node-typescript@1"}

import cmdShim from 'cmd-shim'
import { readFile, stat } from 'node:fs/promises'

export async function generateShims(sourcePath, targetBase) {
  await cmdShim(sourcePath, targetBase)
  const [shContent, cmdContent, ps1Content, shStat] = await Promise.all([
    readFile(targetBase, 'utf8'),
    readFile(`${targetBase}.cmd`, 'utf8'),
    readFile(`${targetBase}.ps1`, 'utf8'),
    stat(targetBase),
  ])
  return {
    shContent,
    cmdContent,
    ps1Content,
    mode: shStat.mode & 0o777,
  }
}

export async function generateShimsIfExists(sourcePath, targetBase) {
  await cmdShim.ifExists(sourcePath, targetBase)
}

{
  "name": "sample-cmd-shim",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-cmd-shim",
      "version": "1.0.0",
      "dependencies": {
        "cmd-shim": "7.0.0"
      }
    },
    "node_modules/cmd-shim": {
      "version": "7.0.0",
      "resolved": "https://registry.npmjs.org/cmd-shim/-/cmd-shim-7.0.0.tgz",
      "integrity": "sha512-rtpaCbr164TPPh+zFdkWpCyZuKkjpAzODfaZCf/SVJZzJN+4bHQb/LP3Jzq5/+84um3XXY8r548XiWKSborwVw==",
      "license": "ISC",
      "engines": {
        "node": "^18.17.0 || >=20.5.0"
      }
    }
  }
}

{
  "name": "sample-cmd-shim",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "cmd-shim": "7.0.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/cmd-shim@7.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/cmd-shim@7.0.0"
  ]
}

import assert from 'node:assert/strict'
import { mkdtemp, rm, stat, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import cmdShim from 'cmd-shim'
import { generateShims, generateShimsIfExists } from '../index.mjs'

const workDir = await mkdtemp(join(tmpdir(), 'cmd-shim-contract-'))

try {
  // 1. Create a script with a node shebang and env var + flag
  const scriptWithShebang = join(workDir, 'cli', 'entry.js')
  const binTarget = join(workDir, 'bin', 'my-cli')
  await generateShimsIfExists(scriptWithShebang, binTarget)

  // Since scriptWithShebang does not exist yet, binTarget should not be created
  await assert.rejects(stat(binTarget), { code: 'ENOENT' })

  // Also verify direct cmdShim rejects when source file is missing
  await assert.rejects(cmdShim(scriptWithShebang, binTarget), { code: 'ENOENT' })

  // Write the actual script file (mkdir happens when we create cli dir or write in workDir directly)
  const directScript = join(workDir, 'runner.js')
  await writeFile(
    directScript,
    '#!/usr/bin/env -S NODE_NO_WARNINGS=1 node --harmony\nconsole.log("ok")\n',
    'utf8'
  )

  const result = await generateShims(directScript, binTarget)

  // Verify sh, .cmd, and .ps1 shims were created with executable permissions and parsed shebang
  assert.ok(result.shContent.startsWith('#!/bin/sh\n'))
  assert.ok(result.shContent.includes('NODE_NO_WARNINGS=1'))
  assert.ok(result.shContent.includes('--harmony'))
  assert.ok(result.shContent.includes('../runner.js'))

  assert.ok(result.cmdContent.startsWith('@ECHO off\r\n'))
  assert.ok(result.cmdContent.includes('@SET NODE_NO_WARNINGS=1\r\n'))
  assert.ok(result.cmdContent.includes('--harmony'))
  assert.ok(result.cmdContent.includes('..\\runner.js'))

  assert.ok(result.ps1Content.startsWith('#!/usr/bin/env pwsh\n'))
  assert.ok(result.ps1Content.includes('--harmony'))
  assert.ok(result.ps1Content.includes('../runner.js'))

  // Verify cmdShim.ifExists creates shims when source file exists
  const secondTarget = join(workDir, 'bin', 'second-cli')
  await generateShimsIfExists(directScript, secondTarget)
  const secondStat = await stat(secondTarget)
  assert.ok(secondStat.isFile())
  const secondCmdStat = await stat(`${secondTarget}.cmd`)
  assert.ok(secondCmdStat.isFile())
  const secondPs1Stat = await stat(`${secondTarget}.ps1`)
  assert.ok(secondPs1Stat.isFile())
} finally {
  await rm(workDir, { recursive: true, force: true })
}