codemap_script_create

Create a new script with category-specific template. Scripts extend CodeMap functionality through custom validation (audit), build automation (build), session contributions (orient/close), or ad-hoc helpers (utility).

scriptcreateextensibility

Parameters

Name	Type	Required	Description
`category`	`string`audit \| build \| orient \| close \| utility	✅ Required	Script category (determines interface requirements)
`name`	`string`	✅ Required	Script name (filename without .js extension)
`template`	`string`	❌ Optional	Optional custom script content (if not provided, generates default template)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_script_create",
  "arguments": {
    "category": "audit",
    "name": "check-imports"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "script": {
    "name": "check-imports",
    "category": "audit",
    "path": ".codemap/scripts/audit/check-imports.js"
  },
  "message": "Script created: audit/check-imports.js",
  "hint": "Reference this script in .codemap/audit-rules.json to use it."
}

ℹ️When to Use This Tool

codemap_script_create

Custom validations - Audit scripts for architecture rules, import patterns, naming conventions
Build automation - Build scripts for pre-commit checks, compilation steps, bundling
Session context - Orient scripts to show project state, TODOs, recent changes
Cleanup tasks - Close scripts for archiving, backups, temp file removal
Ad-hoc utilities - Utility scripts for one-off tasks, experiments, analysis

💡Common Patterns

Standard Script Template

// Auto-generated template structure
module.exports = async (codemap) => {
  // Your logic here
  
  return {
    passed: true, // For audit scripts
    message: 'Script completed'
  };
};

Audit Script Pattern

await codemap.scripts.create({
  category: 'audit',
  name: 'check-naming'
});

// Then reference in .codemap/audit-rules.json:
// { "name": "check-naming", "enabled": true }

Build Script Chain

const buildSteps = ['lint', 'test', 'compile', 'bundle'];

for (const step of buildSteps) {
  await codemap.scripts.create({
    category: 'build',
    name: step
  });
}

Session Lifecycle Hooks

// Orient: Run at session start
await codemap.scripts.create({
  category: 'orient',
  name: 'show-context'
});

// Close: Run at session end
await codemap.scripts.create({
  category: 'close',
  name: 'save-state'
});

💡Pro Tips

Choose category carefully - Category determines when/how the script runs. Audit = validation, build = automation, orient/close = lifecycle, utility = manual.

Use templates for complex logic - Don't rely on default template for production scripts. Provide custom template with proper error handling.

Keep scripts focused - One script = one responsibility. Don't create god scripts that do everything.

Test before deploying - Create in utility category first to test, then move to production category.

Document in code - Include comments explaining what the script does and when it runs.

Handle async properly - Scripts are async by default. Always use await for promises.

✅Best Practices

Name descriptively - Use clear names like 'check-circular-deps' not 'validator1'.

Return proper format - Audit scripts return { passed, message }. Build scripts return success status.

Handle errors gracefully - Wrap logic in try-catch and return meaningful error messages.

Keep lightweight - Scripts should execute quickly (<1s for audit, <5s for build).

Version control - Commit scripts to git so team shares same validation rules.

Use lifecycle categories - Orient/close scripts automate session setup/teardown.

⚠️Common Mistakes

❌ Mistake: Wrong category choice

// Audit script in utility category
await codemap.scripts.create({
  category: 'utility', // Should be 'audit'
  name: 'validate-structure'
});

✅ Instead: Use correct category

await codemap.scripts.create({
  category: 'audit',
  name: 'validate-structure'
});

---

❌ Mistake: Not handling async properly

const template = 
module.exports = async (codemap) => {
  codemap.search({ query: '*.ts' }); // Forgotten await!
  return { passed: true };
};
;

✅ Instead: Always await promises

const template = 
module.exports = async (codemap) => {
  await codemap.search({ query: '*.ts' });
  return { passed: true };
};
;

---

❌ Mistake: Creating scripts without extension

await codemap.scripts.create({
  category: 'audit',
  name: 'check-imports.js' // Don't include .js
});

✅ Instead: Use name without extension

await codemap.scripts.create({
  category: 'audit',
  name: 'check-imports'
});

---

❌ Mistake: Not returning proper format

const template = 
module.exports = async (codemap) => {
  const valid = true;
  // No return statement!
};
;

✅ Instead: Always return result

const template = 
module.exports = async (codemap) => {
  return {
    passed: true,
    message: 'Validation successful'
  };
};
;

---

❌ Mistake: Creating duplicate scripts

await codemap.scripts.create({ category: 'audit', name: 'validate' });
await codemap.scripts.create({ category: 'audit', name: 'validate' });
// Error: Script already exists

✅ Instead: Check existence first

const scripts = await codemap.scripts.list('audit');
if (!scripts.some(s => s.name === 'validate')) {
  await codemap.scripts.create({ category: 'audit', name: 'validate' });
}