Packaging Console Apps — I can package a console app with clear instructions, sample runs, and documented assumptions. - Computer Programming 1 JavaScript

SECTION 1

Historical Context & Motivation

Writing code that works on your own computer is only half the battle. Since the earliest days of computing, developers have faced a persistent challenge: how do you share your program with someone who did not write it? In the 1960s and 1970s, programs were distributed on punched cards and magnetic tapes, and each one came with printed instruction sheets explaining how to load and run the software. Even then, packaging — the act of bundling code with documentation, instructions, and metadata — was considered essential to professional software delivery.

1970s • README Files Emerge

Early UNIX developers began including plain-text README files alongside source code, establishing the convention of documenting how to compile and run a program.

1995 • JavaScript Is Born

Brendan Eich created JavaScript for Netscape Navigator. Initially browser-only, JavaScript would eventually move to the server and command line.

2009 • Node.js & npm Arrive

Ryan Dahl released Node.js, allowing JavaScript to run outside the browser. The npm package manager gave developers a standard way to package and share JavaScript projects.

2010s • Open-Source Culture Explodes

GitHub popularized sharing code worldwide. Well-packaged projects with clear READMEs, sample runs, and documented assumptions attracted contributors and users.

2020s • Professional Packaging Standards

Modern developers are expected to include READMEs, sample output, dependency lists, and assumption documentation for even the smallest console apps.

This history reveals a fundamental truth: code without context is nearly useless to others. The question that drives this lesson is straightforward — how do you package a JavaScript console app so that anyone can understand it, set it up, and run it successfully?

SECTION 2

Core Principles of Packaging

Packaging a console app means organizing your project files and writing documentation so that a new user — someone who has never seen your code — can install, run, and understand your program without asking you any questions. There are several foundational ideas that guide good packaging practice.

Clear Instructions (README)

A README file is a plain-text or Markdown document that tells users what the app does, how to install dependencies, and how to run it. It is the front door of your project.

Sample Runs

Including sample runs — screenshots or copied terminal output showing the app in action — removes guesswork and lets users know exactly what to expect.

Documented Assumptions

Every program makes assumptions — about input format, operating system, Node.js version, or expected data ranges. Writing these down prevents confusion and bugs.

Organized File Structure

A well-structured project folder with a consistent layout (source files, README, configuration files) helps users quickly navigate and understand the codebase.

Dependency Management

If your app uses external libraries, a package.json file lists every dependency so users can install them with a single command.

✦

KEY TAKEAWAY

Think of packaging like handing someone a board game. You would not just give them the pieces — you would include the rule book, a picture of the completed setup, and notes about how many players it supports. A packaged console app is the same: code is the pieces, the README is the rule book, sample runs are the picture on the box, and assumptions are the fine print.

SECTION 3

Visual Explanation — Project Anatomy

This diagram shows the standard file layout for a packaged JavaScript console app. The README.md provides instructions, package.json manages metadata and dependencies, index.js is the entry point, and SAMPLE_OUTPUT.txt shows what a successful run looks like.

Notice that the project folder contains more than just code files. The README.md sits at the top level so it is the first thing a user sees on GitHub or in a file browser. The ASSUMPTIONS.md file is separate from the README to keep things organized, though for smaller projects you can include assumptions as a section inside the README. The SAMPLE_OUTPUT.txt file gives the user a concrete example of what the program prints when it runs correctly, which is invaluable for troubleshooting.

SECTION 4

How It Works — Building Each Piece

The README File

A README is written in Markdown — a lightweight formatting language that uses symbols like # for headings and ``` for code blocks. A strong README for a console app typically includes these sections: a title, a short description, prerequisites, installation steps, usage instructions, a sample run, and assumptions. Here is a template you can adapt for any project.

💡

README.md Template

# My Calculator App

A simple command-line calculator that performs basic arithmetic.

## Prerequisites
- Node.js v16 or higher

## Installation
1. Clone or download this folder
2. Open a terminal in the project directory
3. Run `npm install`

## Usage
```
node index.js
```

## Sample Run
```
$ node index.js
Welcome to Calculator!
Enter first number: 10
Enter operator (+, -, *, /): *
Enter second number: 5
Result: 10 * 5 = 50
```

## Assumptions
- User enters valid numbers
- Division by zero displays an error message
- Only +, -, *, / are supported

The package.json File

The package.json file is created by running npm init in your terminal. It stores your project's name, version, description, entry point, and any dependencies. When another user downloads your project and runs npm install, npm reads this file and automatically installs every library your app needs. Even if your console app has no external dependencies, a package.json is still good practice because it defines the start command and provides metadata.

ℹ

Minimal package.json Example

{
  "name": "my-calculator-app",
  "version": "1.0.0",
  "description": "A simple command-line calculator",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "author": "Your Name",
  "license": "MIT"
}

Documenting Assumptions

Every program makes decisions about what it expects from the user and the environment. These decisions are your assumptions. For example, a grade calculator might assume that scores are between 0 and 100, or that the user will enter a number rather than a word. Writing down your assumptions is important because it tells users the boundaries within which your program is guaranteed to work correctly, and it warns them about what might break.

Input assumptions: What type and range of input does the program expect?
Environment assumptions: What version of Node.js? What operating system?
Behavioral assumptions: What happens with edge cases like empty input or very large numbers?
Scope assumptions: What features are NOT included? What is out of scope?

SECTION 5

Crafting Effective Sample Runs

A sample run is a recorded transcript of your program's input and output. It is one of the most helpful things you can include because it shows users exactly what they should see when they type a command. Good sample runs cover the happy path (normal usage) and at least one edge case (unusual or error-triggering input). Let's look at what makes a sample run effective.

The left terminal shows a happy path where everything works correctly. The right terminal demonstrates an edge case where the user enters invalid data. Good packaging includes both types.

When creating your sample run, open your terminal, run the app, and interact with it exactly as a user would. Then copy and paste the entire session into a file called SAMPLE_OUTPUT.txt or paste it directly into your README inside a Markdown code block. The key is authenticity: do not make up output that your program does not actually produce. Run the program, capture the real output, and include it as-is.

SECTION 6

Worked Example — Packaging a Temperature Converter

Let's walk through the entire process of packaging a simple console app from start to finish. We will package a temperature converter that converts Fahrenheit to Celsius.

Packaging a Temperature Converter App

1
Step 1 — Write the Code

Create a file called index.js with the following code: const readline = require('readline'); const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); rl.question('Enter temperature in Fahrenheit: ', (input) => { const fahrenheit = parseFloat(input); if (isNaN(fahrenheit)) { console.log('Error: Please enter a valid number.'); } else { const celsius = ((fahrenheit - 32) * 5) / 9; console.log(`${fahrenheit}°F = ${celsius.toFixed(2)}°C`); } rl.close(); });

Core logic complete — converts °F to °C with basic input validation.
2
Step 2 — Initialize package.json

Open your terminal in the project folder and run npm init -y to generate a default package.json. Then edit it to add a meaningful description and a start script. Set "scripts": { "start": "node index.js" } so users can also run the app with npm start.

package.json created with name, version, description, and start script.
3
Step 3 — Run the App and Capture Sample Output

Run the app by typing node index.js in the terminal. Interact with it and copy the full session. Run it at least twice — once with a normal value (like 212) and once with bad input (like "abc"). Save this as SAMPLE_OUTPUT.txt: $ node index.js Enter temperature in Fahrenheit: 212 212°F = 100.00°C $ node index.js Enter temperature in Fahrenheit: abc Error: Please enter a valid number.

Two sample runs captured — one happy path (212°F) and one error case ("abc").
4
Step 4 — Document Assumptions

Think about what your program assumes. Write an ASSUMPTIONS section in your README or create a separate file. For this app, the assumptions include: the user enters a single number, the input is in Fahrenheit, the program only converts one temperature per run, and the output is rounded to two decimal places.

Four assumptions documented clearly.
5
Step 5 — Write the README

Combine everything into a README.md file with these sections: Title, Description, Prerequisites (Node.js v16+), Installation (clone + npm install), Usage (node index.js or npm start), Sample Run (paste from Step 3), and Assumptions (paste from Step 4). Add a .gitignore file with node_modules/ so users do not accidentally upload dependencies.

Project is fully packaged and ready to share!

SECTION 7

Well-Packaged vs. Poorly-Packaged Apps

To appreciate why packaging matters, let's compare what it looks like when a project is well-packaged versus when it is not. Imagine you receive two project folders from classmates. One is a dream to run, and the other is a frustrating puzzle. The difference is entirely in how they are packaged.

Aspect	Well-Packaged ✓	Poorly-Packaged ✗
README	Clear title, installation steps, usage command, and sample runs	Missing entirely, or says only "my project"
Sample Run	Shows happy path and edge case with actual terminal output	No sample output — user must guess what is correct
Assumptions	Input types, ranges, and limitations explicitly listed	Not mentioned — app crashes on unexpected input
File Structure	Organized with clear file names and a .gitignore	All code in one giant file named "stuff.js"
Dependencies	package.json lists all dependencies; npm install works	Missing package.json or node_modules committed to repo
Time to First Run	Under 2 minutes from download to working output	30+ minutes of troubleshooting and guessing

Comparison of well-packaged versus poorly-packaged console applications

✦

KEY TAKEAWAY

Think of your packaged app like a recipe card at a potluck. A well-written recipe card lists ingredients, step-by-step instructions, cooking time, and notes like "substitute almond milk for dairy-free option." A bad recipe card just says "make the thing." The goal of packaging is to make your project a five-star recipe card that anyone can follow.

SECTION 8

Connection to Professional Practices

The packaging skills you learn in this lesson are the foundation of professional software development practices. In the real world, teams use these same concepts but at a larger scale. Understanding where basic packaging leads helps you see why these habits matter even for small school projects.

What You Learn Now	Professional Equivalent
README.md with installation and usage instructions	Full documentation sites, API reference docs, onboarding guides
Sample runs pasted into text files	Automated testing (unit tests, integration tests) that verify output
Documented assumptions in a list	Technical specification documents and design decision records
package.json with scripts	CI/CD pipelines, Docker containers, deployment configurations
.gitignore to exclude node_modules	Build artifacts management, security-sensitive file exclusion

How beginner packaging skills map to professional software engineering practices

As you progress into more advanced courses and eventually into internships or jobs, you will encounter tools like Docker (which packages entire environments, not just code), Jest (which automates the process of checking sample runs), and GitHub Actions (which automatically tests and deploys your project when you push code). All of these build on the same fundamental idea: make your project reproducible and understandable by others.

ℹ

Looking Ahead

In Computer Programming 2, you may learn to write automated tests using frameworks like Jest. These tests are essentially machine-readable sample runs — they run your code, check the output against expected values, and tell you instantly whether anything is broken.

SECTION 9

Practice Problems

Question 1: CONCEPTUAL

A classmate sends you a JavaScript project folder that contains only one file: app.js. There is no README, no package.json, and no sample output. List three specific problems you might encounter trying to run their project, and explain which packaging file would have prevented each problem.

Show answer

First, you would not know how to run the app — you might try node app.js but the file might require arguments you do not know about. A README with a "Usage" section would solve this. Second, if the project uses external libraries (like readline-sync), you would get a "Cannot find module" error because there is no package.json to tell npm what to install. Third, you would not know what kind of input the program expects, so you might enter text when it needs a number, causing a crash. Documented assumptions would clarify the expected input format.

Question 2: BASIC CALCULATION

Write a complete package.json file for a console app called "number-guesser" at version 1.0.0. The main file is game.js, it has no external dependencies, and you should include a start script. Your name is the author.

Show answer

A correct package.json would look like this:

{
  "name": "number-guesser",
  "version": "1.0.0",
  "description": "A number guessing game for the command line",
  "main": "game.js",
  "scripts": {
    "start": "node game.js"
  },
  "author": "Your Name",
  "license": "MIT"
}

The key elements are: the "name" field uses lowercase with hyphens (no spaces), "main" points to game.js instead of the default index.js, and the "start" script runs node game.js so users can type npm start to launch the app.

Question 3: INTERMEDIATE

You are building a "tip calculator" console app. The user enters a bill amount and a tip percentage, and the program displays the tip amount and total. Write the Assumptions section of your README, listing at least four assumptions. For each assumption, explain why it matters.

Show answer

A strong assumptions section might include: (1) The bill amount is a positive number — this matters because negative bills do not make sense and the app does not handle them. (2) The tip percentage is entered as a whole number (e.g., 15 for 15%), not a decimal (e.g., 0.15) — this matters because the calculation would produce wrong results if the user enters the wrong format. (3) The app does not split the bill among multiple people — users expecting a bill-splitting feature will not find one. (4) Currency is assumed to be USD and output is rounded to two decimal places — this prevents confusion for users in other countries. Each assumption draws a boundary around what the program can and cannot do, helping users avoid frustration.

Question 4: APPLIED

Your teacher asks you to submit a packaged "word counter" app that reads a sentence from the user and outputs the number of words. Write the complete README.md content in Markdown format, including: title, description, prerequisites, installation, usage, at least two sample runs (one happy path, one edge case), and assumptions.

Show answer

A well-structured README would begin with # Word Counter followed by a one-line description like "A command-line tool that counts the number of words in a sentence." Prerequisites should list Node.js v16+. Installation tells users to clone the repo and run npm install. Usage shows node index.js. The happy path sample run shows: Enter a sentence → "The quick brown fox" → Word count: 4. The edge case might show entering an empty string → Word count: 0 (or a message like "No words entered"). Assumptions should state: the app counts words by splitting on spaces, multiple consecutive spaces may result in an inaccurate count, punctuation attached to words counts as part of the word, and the app processes one sentence per run. This complete README gives any user everything they need to run and understand the project.

Question 5: CRITICAL THINKING

A developer argues: "I do not need to document my assumptions because my code is the documentation — anyone can just read it." Write a thoughtful response explaining why this approach fails, using at least two specific examples where reading the code alone would not tell a user what they need to know.

Show answer

While code does describe what a program does mechanically, it does not explain the developer's intentions or design decisions. First, consider input validation: if the code uses parseFloat(input) without range-checking, a code reader cannot tell whether the developer intentionally allows negative numbers or simply forgot to handle them. An assumption document clarifies this intent. Second, consider scope: the code might only convert Fahrenheit to Celsius, but a user reading the code cannot quickly determine whether Celsius-to-Fahrenheit conversion was intentionally excluded or just not implemented yet. Documented assumptions make this explicit. Furthermore, many users who need to run a program are not experienced developers and cannot quickly parse JavaScript logic. Even experienced developers would need to trace through the code line by line to understand the expected usage pattern, whereas a README sample run communicates this in seconds. Documentation is about communicating intent and context, which code alone cannot do.

SUMMARY

Lesson Summary

Summary

Packaging a console app means delivering more than just code. A fully packaged JavaScript project includes a README.md with clear installation and usage instructions, a package.json that manages metadata and dependencies, authentic sample runs showing both happy paths and edge cases, and explicitly documented assumptions about input, environment, and scope. Together, these elements ensure that anyone can download, install, and run your app without needing to ask you a single question.

The habits you build here — writing documentation, capturing real output, and thinking about your user's experience — are the same habits used by professional software engineers worldwide. Whether you are sharing a project with a classmate or publishing an open-source tool on npm, the principle remains the same: great code deserves great packaging.