scriptplan 0.9.1

A precise project scheduling engine with minute-level accuracy for resource allocation and dependency management.

ScriptPlan

A precise project scheduling engine with minute-level accuracy for resource allocation and dependency management. The syntax is compatible with TaskJuggler (.tjp files).

Installation

pip install scriptplan

Quick Start

Report Generation (Unix-style)

# Generate JSON report to stdout
plan report project.tjp

# Generate CSV report
plan report --csv project.tjp

# Save to file
plan report project.tjp > output.json
plan report --csv project.tjp > output.csv

# Read from stdin
cat project.tjp | plan report
plan report - < project.tjp

# Pipe to other tools
plan report project.tjp | jq '.data[0]'
plan report --csv project.tjp | csvkit

# Process multiple files
for f in projects/*.tjp; do
  plan report "$f" | jq -r '.report_id'
done

Output Format (JSON):

{
  "data": [
    {
      "id": "project.task1",
      "start": "2024-01-01-09:00",
      "end": "2024-01-05-17:00"
    }
  ],
  "columns": ["id", "start", "end"],
  "report_id": "ea3f901dd6426dfa58288d945819c75485fd9ff1875db59def350f219e2d62ca"
}

Features:

• Output to stdout (Unix philosophy)
• Messages to stderr
• SHA256 report_id (content-based hash)
• Lowercase column names
• No HTML metadata
• No file pollution (uses temp directories)
• Safe for concurrent execution (100+ instances)

Python API

from scriptplan.parser.tjp_parser import ProjectFileParser

parser = ProjectFileParser()
project = parser.parse(open('project.tjp').read())

# Access scheduled tasks
for task in project.tasks:
    if task.leaf():
        start = task.get('start', 0)
        end = task.get('end', 0)
        print(f"{task.id}: {start} -> {end}")

System Certified

Certification Level: Airport-Grade / Mission Critical

Capabilities Verified:

• Temporal Physics: Floating point precision, Timezones, DST awareness, Date Line crossing.

• Resource Constraints: Daily/Weekly limits, Hierarchical quotas, Shift intersections.

• Advanced Scheduling: ALAP (Backward pass), Priority preemption, Smart Resource Selection (Failover).

• Workflow Logic: Atomicity (Contiguous), Perishability (Max Gap), Zero-Buffer Synchronization.

Features

• Minute-level scheduling precision
• ASAP and ALAP scheduling modes
• Resource allocation with contention handling
• Working hours and shift definitions
• Dependency chains with gap constraints
• Leap year and timezone handling

Accuracy

ScriptPlan uses integer arithmetic for all time calculations, avoiding floating-point drift. The scheduler correctly handles:

• Non-standard shift boundaries (e.g., 08:13 - 11:59, 13:07 - 17:47)
• Prime-number effort durations with prime-number gaps
• Resource contention across multi-day tasks
• Calendar gaps (weekends, holidays) vs working time gaps

Example: A chain of 500 tasks, each with 73-minute effort and 29-minute gaps, scheduled across leap year boundaries with non-standard shifts, produces exact minute-aligned results.

Example Project

project "Manufacturing" 2025-07-01 +1m {
  timezone "Etc/UTC"
  timeformat "%Y-%m-%d %H:%M"
  scheduling alap
}

shift factory_hours "Factory Hours" {
  workinghours mon - fri 08:00 - 16:00
}

resource machine "Press" {
  workinghours factory_hours
}

task delivery "Product Launch" {
  end 2025-07-18-16:00

  task pack "Packaging" {
    effort 8h
    allocate machine
  }

  task assemble_b "Body Assembly" {
    effort 16h
    allocate machine
    depends !!pack { onstart }
  }

  task assemble_a "Engine Assembly" {
    effort 16h
    allocate machine
  }
}

task connection_setup "Logic" {
  task set_deps "Apply" {
    depends !delivery.assemble_a, !delivery.assemble_b
    precedes !delivery.pack
  }
}

taskreport output "output" {
  formats csv
  columns id, start, end
  timeformat "%Y-%m-%d-%H:%M"
}

This project schedules backward from the delivery deadline (ALAP mode). The scheduler:

1. Anchors packaging to end at 16:00 on July 18
2. Schedules both assembly tasks to complete before packaging starts
3. Resolves resource contention (single machine) by sequencing assemblies back-to-back
4. Respects weekend boundaries (Mon-Fri working hours)

Result:

delivery.pack:       2025-07-18-08:00 -> 2025-07-18-16:00
delivery.assemble_a: 2025-07-14-08:00 -> 2025-07-15-16:00
delivery.assemble_b: 2025-07-16-08:00 -> 2025-07-17-16:00

License

Apache 2.0

Why?

This scheduler is part of Highway Workflow Egnine's worker capacity management system. I decided to open-source it for the community to benefit from its precise scheduling capabilities. Thanks to TaskJuggler's established syntax, users can easily adopt ScriptPlan without learning a new format. Credits to TaskJuggler for the original project definition language and concepts.

Yours, Farshid.