sources

sources is a simple command-line tool that can fetch resources from the web and save them to your local file system.

It's a poor man's package manager in that it can download and extract packages for me when creating a new project.

If you prefer a real package manager, please see any of the following:

• Bower
• Component
• Jam
• Volo

Those all seem very useful, but I like being in control of exactly what files I add to my projects and I don't like not being able to use a package manager because the project I need doesn't have the magic JSON file in its repository.

With sources, I can define the sources for packages on my machine. I don't have to wait for a project to adopt any conventions and I can select the exact files I need.

Sources are defined in a file called sources.json:

{
    "jquery": "http://code.jquery.com/jquery.js",
    "bootstrap": [
        "jquery",
        "http://twitter.github.com/bootstrap/assets/bootstrap.zip"
    ],
    "qunit": [
        "http://code.jquery.com/qunit/qunit-1.11.0.js",
        "http://code.jquery.com/qunit/qunit-1.11.0.css"
    ]
}

With something like that in my current or home directory I can type:

sources bootstrap

and the latest jQuery and Bootstrap files will be fetched and extracted into the current directory.

Later on, if I decide I need to write some tests, I can type:

sources qunit

to fetch the QUnit files.

That's really all there is to it.

Yes, it kind of resolves dependencies for me, but only if I define those dependencies myself.

Yes, it fetches the latest versions of jQuery and Bootstrap, but only because URLs exist for the latest versions. If a new version of QUnit is released, I won't get that because I don't know of a URL for the latest version of QUnit.

Finding Sources

The sources for packages are defined in files named sources.json.

sources will look in the following locations for sources.json files:

• the current directory
• all parent directories of the current directory
• the home directory
• the sources script's directory

Locations higher on that list override locations lower on that list.

The contents of sources.json files are a JSON object like this:

{
    "jquery": "http://code.jquery.com/jquery.js",
    "bootstrap": [
        "jquery",
        "http://twitter.github.com/bootstrap/assets/bootstrap.zip"
    ],
    "qunit": [
        "http://code.jquery.com/qunit/qunit-1.11.0.js",
        "http://code.jquery.com/qunit/qunit-1.11.0.css"
    ]
}

The keys in those objects are the names of the packages as I've defined them.

The values can be URLs or arrays of URLs to fetch from.

If a URL references an archive, that archive is extracted into the current directory and then the archive is deleted.

If a URL is the name of another package, that other package is fetched, too.

TODO:

• write to lib folder?

• look for sources.json inside lib folders, too?

• look for lib folder up path?

• caching?

• other archive formats?

• extract specific files from archives? (to exclude minified files, docs, tests, etc)

  "bootstrap": [ "jquery", { "http://twitter.github.com/bootstrap/assets/bootstrap.zip": [ "css/bootstrap.css", "css/bootstrap-responsive.css", "img/*", "js/bootstrap.js" ] } ]

• rename files?

  "qunit": [ "http://code.jquery.com/qunit/qunit-1.11.0.js => qunit.js", "http://code.jquery.com/qunit/qunit-1.11.0.css => qunit.css" ]